Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Change if keyword to assert #80

Merged
merged 2 commits into from
Jul 21, 2020
Merged

Change if keyword to assert #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51278ed
Switch keyword from `if` to `assert` in README and spec.
dandclark Jul 16, 2020
d1c5f89
Add 'no LineTerminator here' before AssertClauses
dandclark Jul 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ The Import Conditions and JSON modules proposal adds:

Developers will then be able to import a JSON module as follows:
```js
import json from "./foo.json" if { type: "json" };
import("foo.json", { if: { type: "json" } })
import json from "./foo.json" assert { type: "json" };
import("foo.json", { assert: { type: "json" } })
```

## Motivation
Expand Down Expand Up @@ -52,32 +52,32 @@ Here, a key-value syntax is used, with the key `type` used as an example indicat

### import statements

The ImportDeclaration would allow any arbitrary conditions after the `if` keyword.
The ImportDeclaration would allow any arbitrary conditions after the `assert` keyword.

For example, the `type` attribute indicates a module type, and can be used to load JSON modules with the following syntax.

```mjs
import json from "./foo.json" if { type: "json" };
import json from "./foo.json" assert { type: "json" };
```

The `if` syntax in the `ImportDeclaration` statement uses curly braces, for the following reasons (as discussed in [#5](https://github.com/tc39/proposal-import-conditions/issues/5)):
The `assert` syntax in the `ImportDeclaration` statement uses curly braces, for the following reasons (as discussed in [#5](https://github.com/tc39/proposal-import-conditions/issues/5)):
- JavaScript developers are already used to the Object literal syntax and since it allows a trailing comma copy/pasting conditions will be easy.
- Follow-up proposals might specify new types of import conditions (see [Restriction to condition attributes](https://github.com/tc39/proposal-import-conditions#restriction-to-condition-attributes)) and we will be able to group conditions with different keywords, for instance:
```js
import json from "./foo.json" if { type: "json" } with { transformA: "value" };
import json from "./foo.json" assert { type: "json" } with { transformA: "value" };
```

The `if` keyword is designed to match the check-only semantics. As shown by the example above, one could imagine a new follow-up proposal that uses `with` for transformations.
The `assert` keyword is designed to match the check-only semantics. As shown by the example above, one could imagine a new follow-up proposal that uses `with` for transformations.

### dynamic import()

The `import()` pseudo-function would allow import conditions to be indicated in an options bag in the second argument.

```js
import("foo.json", { if: { type: "json" } })
import("foo.json", { assert: { type: "json" } })
```

The second parameter to `import()` is an options bag, with the only option currently defined to be `if`: the value here is an object containing the import conditions. There are no other current proposals for entries to put in the options bag, but better safe than sorry with forward-compatibility.
The second parameter to `import()` is an options bag, with the only option currently defined to be `assert`: the value here is an object containing the import conditions. There are no other current proposals for entries to put in the options bag, but better safe than sorry with forward-compatibility.

### Integration of modules into environments

Expand All @@ -86,17 +86,17 @@ Host environments (e.g., the Web platform, Node.js) often provide various differ
#### Worker instantiation

```js
new Worker("foo.wasm", { type: "module", if: { type: "webassembly" } });
new Worker("foo.wasm", { type: "module", assert: { type: "webassembly" } });
```

Sidebar about WebAssembly module types and the web: it's still uncertain whether importing WebAssembly modules would need to be marked specially, or would be imported just like JavaScript. Further discussion in [#19](https://github.com/tc39/proposal-import-conditions/issues/19).

#### HTML

Although changes to HTML won't be specified by TC39, an idea here would be that each import attribute, preceded by `if`, becomes an HTML attribute which could be used in script tags.
Although changes to HTML won't be specified by TC39, an idea here would be that each import attribute, preceded by `assert`, becomes an HTML attribute which could be used in script tags.

```html
<script src="foo.wasm" type="module" iftype="webassembly"></script>
<script src="foo.wasm" type="module" asserttype="webassembly"></script>
```

(See the caveat about WebAssembly above.)
Expand All @@ -109,15 +109,15 @@ In the context of the [WebAssembly/ESM integration proposal](https://github.com/

### JSON modules

JSON modules are required to be supported when invoked using the `if { type: "json" }` syntax, with common semantics in all JavaScript implementations for this syntax.
JSON modules are required to be supported when invoked using the `assert { type: "json" }` syntax, with common semantics in all JavaScript implementations for this syntax.

JSON modules' semantics are those of a single default export which is the entire parsed JSON document.

All of the import statements in the module graph that address the same JSON module will evaluate to the same mutable object as discussed in [#54](https://github.com/tc39/proposal-import-attributes/issues/54).

Each JavaScript host is expected to provide a secondary way of checking whether a module is a JSON module. For example, on the Web, the MIME type would be checked to be a JSON MIME type. In "local" desktop/server/embedded environments, the file extension may be checked (possibly after symlinks are followed). The `type: "json"` is indicated at the import site, rather than *only* through that other mechanism in order to prevent the privilege escalation issue noted in the opening section.

Nevertheless, the interpretation of module loads with no conditions remains host/implementation-defined, so it is valid to implement JSON modules without *requiring* `if { type: "json" }`. It's just that `if { type: "json" }` must be supported everywhere. For example, it will be up to Node.js, not TC39, to decide whether import conditions are required or optional for JSON modules.
Nevertheless, the interpretation of module loads with no conditions remains host/implementation-defined, so it is valid to implement JSON modules without *requiring* `assert { type: "json" }`. It's just that `assert { type: "json" }` must be supported everywhere. For example, it will be up to Node.js, not TC39, to decide whether import conditions are required or optional for JSON modules.

### Import conditions

Expand Down Expand Up @@ -185,7 +185,7 @@ Another option considered and not selected has been to use a single string as th
We could permit import conditions to have more complex values than simply strings, for example:

```js
import value from "module" if attr: { key1: "value1", key2: [1, 2, 3] };
import value from "module" assert attr: { key1: "value1", key2: [1, 2, 3] };
```

This would allow import conditions to scale to support a larger variety of metadata.
Expand All @@ -210,14 +210,14 @@ import value from "module" as "json";
import value from "module" with type: "json";

// Current proposal, to settle on before Stage 3
import value from "module" if { type: "json" };
import value from "module" assert { type: "json" };
```

#### Before stage 3

After Stage 2 and before Stage 3, we're open to settling on some less core details, such as:

- Considering alternatives for the `with`/`if` keywords ([#3](https://github.com/tc39/proposal-import-conditions/issues/3))
- Considering alternatives for the `with`/`if`/`assert` keywords ([#3](https://github.com/tc39/proposal-import-conditions/issues/3))

```mjs
import value from "module" when { type: 'json' };
Expand All @@ -226,12 +226,12 @@ import value from "module" given { type: 'json' };

- How dynamic import would accept import conditions:
```mjs
import("foo.wasm", { if: { type: "webassembly" } });
import("foo.wasm", { assert: { type: "webassembly" } });
```

For consistency the `if` key is used for both dynamic and static imports.
For consistency the `assert` key is used for both dynamic and static imports.

An alternative would be to remove the `if` nesting in the object:
An alternative would be to remove the `assert` nesting in the object:
```mjs
import("foo.wasm", { type: "webassembly" });
```
Expand All @@ -244,7 +244,7 @@ However, that's not possible with the `Worker` API since it already uses an obje
- For example, in the Web Platform, how import conditions would be enabled when launching a worker (if that is supported in the initial version to be shipped on the Web) or included in a `<script>` tag.

```mjs
new Worker("foo.wasm", { type: "module", if: { type: "webassembly" } });
new Worker("foo.wasm", { type: "module", assert: { type: "webassembly" } });
```

Standardization here would consist of building consensus not just in TC39 but also in WHATWG HTML as well as the Node.js ESM effort and a general audit of semantic requirements across various host environments ([#10](https://github.com/tc39/proposal-import-conditions/issues/10), [#24](https://github.com/tc39/proposal-import-conditions/issues/24) and [#25](https://github.com/tc39/proposal-import-conditions/issues/25)).
Expand Down
38 changes: 19 additions & 19 deletions spec.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,21 +23,21 @@ <h1>Syntax</h1>
ImportDeclaration :
`import` ImportClause FromClause `;`
`import` ModuleSpecifier `;`
<ins>`import` ImportClause FromClause IfClause `;`</ins>
<ins>`import` ModuleSpecifier IfClause `;`</ins>
<ins>`import` ImportClause FromClause [no LineTerminator here] AssertClause `;`</ins>
<ins>`import` ModuleSpecifier [no LineTerminator here] AssertClause `;`</ins>

ExportDeclaration :
`export` ExportFromClause FromClause `;`
<ins>`export` ExportFromClause FromClause IfClause `;`</ins>
<ins>`export` ExportFromClause FromClause [no LineTerminator here] AssertClause `;`</ins>
dandclark marked this conversation as resolved.
Show resolved Hide resolved
`export` NamedExports `;`
`export` VariableStatement[~Yield, ~Await]
`export` Declaration[~Yield, ~Await]
`export` `default` HoistableDeclaration[~Yield, ~Await, +Default]
`export` `default` ClassDeclaration[~Yield, ~Await, +Default]
`export` `default` [lookahead &lt;! {`function`, `async` [no |LineTerminator| here] `function`, `class`}] AssignmentExpression[+In, ~Yield, ~Await] `;`

IfClause :
<ins>`if` `{` ConditionEntries `,`? `}`</ins>
AssertClause :
<ins>`assert` `{` ConditionEntries `,`? `}`</ins>

ConditionEntries :
<ins>IdentifierName `:` StringLiteral</ins>
Expand All @@ -52,7 +52,7 @@ <h1>Syntax</h1>
<emu-clause id="sec-semantics">
<h1>Semantics</h1>

<emu-note type="editor"><p>Many productions operating on grammar are the same whether or not an |IfClause|/second |ImportCall| parameter is included; the new parameter is ignored. In this section, only the semantically significant changes are included, and the PR to merge into the main specification would fill in the straightforward details.</p></emu-note>
<emu-note type="editor"><p>Many productions operating on grammar are the same whether or not an |AssertClause|/second |ImportCall| parameter is included; the new parameter is ignored. In this section, only the semantically significant changes are included, and the PR to merge into the main specification would fill in the straightforward details.</p></emu-note>

<emu-clause id="sec-import-calls">
<h1>Import Calls</h1>
Expand Down Expand Up @@ -85,7 +85,7 @@ <h1>Runtime Semantics: Evaluation</h1>
1. <ins>Let _arg_ be ? GetValue(_argRef_).</ins>
1. <ins>If _arg_ is *undefined*, let _conditions_ be an empty List.</ins>
1. <ins>Otherwise,</ins>
1. <ins>Let _conditionsObj_ be ? Get(_arg_, *"if"*).</ins>
1. <ins>Let _conditionsObj_ be ? Get(_arg_, *"assert"*).</ins>
1. <ins>Let _conditions_ be a new empty List.</ins>
1. <ins>Let _keys_ be EnumerableOwnPropertyNames(_conditionsObj_, ~key~).</ins>
1. <ins>IfAbruptRejectPromise(_keys_, _promiseCapability_).</ins>
Expand Down Expand Up @@ -375,19 +375,19 @@ <h1>ParseJSONModule ( _source_ )</h1>
</emu-alg>
</emu-clause>

<emu-clause id="sec-if-clause-early-errors">
<emu-clause id="sec-assert-clause-early-errors">
<h1>Static Semantics: Early Errors</h1>
<emu-grammar>IfClause : `if` `{` ConditionEntries `,`? `}`</emu-grammar>
<emu-grammar>AssertClause : `assert` `{` ConditionEntries `,`? `}`</emu-grammar>
<ul>
<li>It is a Syntax Error if IfClauseToConditions of |IfClause| has two entries _a_ and _b_ such that _a_.[[Key]] is _b_.[[Key]].</li>
<li>It is a Syntax Error if AssertClauseToConditions of |AssertClause| has two entries _a_ and _b_ such that _a_.[[Key]] is _b_.[[Key]].</li>
</ul>
</emu-clause>

<emu-clause id="sec-if-clause-to-conditions" aoid="IfClauseToConditions">
<h1>Runtime Semantics: IfClauseToConditions</h1>
<emu-grammar>IfClause : `if` `{` ConditionEntries `,`? `}`</emu-grammar>
<emu-clause id="sec-assert-clause-to-conditions" aoid="AssertClauseToConditions">
<h1>Runtime Semantics: AssertClauseToConditions</h1>
<emu-grammar>AssertClause : `assert` `{` ConditionEntries `,`? `}`</emu-grammar>
<emu-alg>
1. Let _conditions_ be IfClauseToConditions of |ConditionEntries|.
1. Let _conditions_ be AssertClauseToConditions of |ConditionEntries|.
1. Sort _conditions_ by the code point order of the [[Key]] of each entry. NOTE: This sorting is observable only in that hosts are prohibited from distinguishing among conditions by the order they occur in.
1. Return _conditions_.
</emu-alg>
Expand All @@ -401,7 +401,7 @@ <h1>Runtime Semantics: IfClauseToConditions</h1>
<emu-grammar> ConditionEntries : IdentifierName `:` StringLiteral `,` ConditionEntries </emu-grammar>
<emu-alg>
1. Let _entry_ be a Record { [[Key]]: StringValue of |IdentifierName|, [[Value]]: StringValue of |StringLiteral| }.
1. Let _rest_ be IfClauseToConditions of |ConditionEntries|.
1. Let _rest_ be AssertClauseToConditions of |ConditionEntries|.
1. Return a new List containing _entry_ followed by the entries of _rest_.
</emu-alg>
</emu-clause>
Expand Down Expand Up @@ -590,10 +590,10 @@ <h1>Static Semantics: ModuleRequests</h1>
1. <ins>Let _specifier_ be StringValue of the |StringLiteral| contained in |FromClause|.</ins>
1. <ins>Return a ModuleRequest Record { [[Specifer]]: _specifier_, [[Conditions]]: an empty List }.</ins>
</emu-alg>
<emu-grammar>ImportDeclaration : `import` ImportClause FromClause IfClause `;`</emu-grammar>
<emu-grammar>ImportDeclaration : `import` ImportClause FromClause AssertClause `;`</emu-grammar>
<emu-alg>
1. <ins>Let _specifier_ be StringValue of the |StringLiteral| contained in |FromClause|.</ins>
1. <ins>Let _conditions_ be IfClauseToConditions of |IfClause|.</ins>
1. <ins>Let _conditions_ be AssertClauseToConditions of |AssertClause|.</ins>
1. <ins>Return a ModuleRequest Record { [[Specifer]]: _specifier_, [[Conditions]]: _conditions_ }.</ins>
</emu-alg>
<emu-grammar>Module : [empty]</emu-grammar>
Expand Down Expand Up @@ -625,11 +625,11 @@ <h1>Static Semantics: ModuleRequests</h1>
1. <ins>Return a ModuleRequest Record { [[Specifer]]: _specifier_, [[Conditions]]: an empty List }.</ins>
</emu-alg>
<emu-grammar>
ExportDeclaration : `export` ExportFromClause FromClause IfClause `;`
ExportDeclaration : `export` ExportFromClause FromClause AssertClause `;`
</emu-grammar>
<emu-alg>
1. <ins>Let _specifier_ be StringValue of the |StringLiteral| contained in |FromClause|.</ins>
1. <ins>Let _conditions_ be IfClauseToConditions of |IfClause|.</ins>
1. <ins>Let _conditions_ be AssertClauseToConditions of |AssertClause|.</ins>
1. <ins>Return a ModuleRequest Record { [[Specifer]]: _specifier_, [[Conditions]]: _conditions_ }.</ins>
</emu-alg>
<emu-grammar>
Expand Down