functionalscript 0.3.4 → 0.3.5

package/issues/lang/1000-json.md

@@ -1,50 +0,0 @@
-# JSON
-
-JSON forms a tree of values.
-
-```json
-{
-    "a": null,
-    "b": [-42.5, false, "hello"]
-}
-```
-
-File extension: `.json`.
-
-## NPN (Normal Polish Notation)
-
-We will use [NPN](https://en.wikipedia.org/wiki/Polish_notation) as a command format for our VM because it allows us to allocate required objects during streaming as a stack automata.
-
-
-```js
-{2} "a" null "b" [3] -42.5 false "hello"
-
-// evolution
-<> {2} "a" null "b" [3] -42.5 false "hello"
-{ ?: ?, ?: ? } <{4}> "a" null "b" [3] -42.5 false "hello"
-{ "a": ?, ?: ? } <{3}> null "b" [3] -42.5 false "hello"
-{ "a": null, ?: ? } <{2}> "b" [3] -42.5 false "hello"
-{ "a": null, "b": ? } <{1}> [3] -42.5 false "hello"
-{ "a": null, "b": [?, ?, ?] } <{0}[3]> -42.5 false "hello"
-{ "a": null, "b": [-42.5, ?, ?] } <{0}[2]> false "hello"
-{ "a": null, "b": [-42.5, false, ?] } <{0}[1]> "hello"
-{ "a": null, "b": [-42.5, false, "hello"] } <>
-```
-
-## RPN, just for fun
-
-[Reverse Polish Notation](https://en.wikipedia.org/wiki/Reverse_Polish_notation):
-
-```js
-"a" null "b" -42.5 false "hello" [3] {2}
-
-// evolution:
-"a" <> null "b" -42.5 false "hello" [3] {2}
-"a" null <> "b" -42.5 false "hello" [3] {2}
-"a" null "b" <> -42.5 false "hello" [3] {2}
-"a" null "b" -42.5 <> false "hello" [3] {2}
-"a" null "b" -42.5 false <> "hello" [3] {2}
-"a" null "b" -42.5 false "hello" <> [3] {2}
-"a" null "b" [-42.5, false, "hello"] <> {2}
-{ "a" : null, "b": [-42.5, false, "hello"] } <>
-```

package/issues/lang/2110-default-export.md

@@ -1,11 +0,0 @@
-# Default Export
-
-Parse `export default` and then JSON. This is enough to have the same functionality as JSON.
-
-```js
-export default 5
-```
-
-Depends on [JSON](./1000-json.md)
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export#using_the_default_export.

package/issues/lang/2120-const.md

@@ -1,14 +0,0 @@
-# Constants
-
-This is enough to provide basic DJS graph and serialization.
-
-```js
-const a = null
-export default {
-    "a": a,
-}
-```
-
-Depends on [default-export](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const

package/issues/lang/2130-default-import.md

@@ -1,10 +0,0 @@
-# Default Import
-
-```js
-import a from './a.d.mjs'
-export default [a]
-```
-
-Depends on [default-export](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#default_import.

package/issues/lang/2210-block-comment.md

@@ -1,12 +0,0 @@
-# Block Comment
-
-We need it to declare JSDoc/TypeScript types.
-
-```js
-/** @type {number} */
-export default -42.5
-```
-
-Depends on [default-export](./2110-default-export.md).
-
-See <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#line_comments>

package/issues/lang/2220-namespace-import.md

@@ -1,25 +0,0 @@
-# Namespace Import
-
-We need it to import types from other modules.
-
-```js
-import * as A from './a.d.mjs'
-/** @type {A.Type} */
-export default [5]
-```
-
-Where `./a.d.mjs` may look like this:
-
-```js
-// this type can be used in other modules
-/** @typedef {readonly [number]} Type */
-
-// export nothing
-export default null
-```
-
-FunctionalScript should use namespace import only as a mechanism to reference type definitions. Since, VM doesn't analyze types, namespace import can be ignored be VM. However different linters, such as TypeScript, can use the information.
-
-Depends on [default-import](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#namespace_import

package/issues/lang/2310-undefined.md

@@ -1,7 +0,0 @@
-# Undefined Type
-
-```js
-export default undefined
-```
-
-Depend on [default-export](./2110-default-export.md).

package/issues/lang/2320-bigint.md

@@ -1,7 +0,0 @@
-# BigInt
-
-```js
-export default 34n
-```
-
-Depend on [default-export](./2110-default-export.md).

package/issues/lang/2330-property-accessor.md

@@ -1,225 +0,0 @@
-# Get Property
-
-```js
-const own_property = a => b => Object.getOwnPropertyDescriptor(obj, property)?.value
-// Or
-const own_property = a => b => Object.hasOwn(obj, property) ? obj[property] : void 0
-```
-
-It's translated into the VM command `own_property`:
-
-```rust
-struct OwnProperty {
-    obj: Expression
-    property: Expression
-}
-```
-
-## Instance Property
-
-```js
-obj.property
-obj.['property']
-```
-
-It's translated into the VM command `instance_property`:
-
-```rust
-struct InstanceProperty {
-    obj: Expression
-    index: u8
-}
-```
-
-If the property name is one of the implemented property names, it should be translated into `index: u8`.
-
-If a property name is one of the prohibited property names or one of the method names, then it's a compilation error.
-
-All other property names generate `own_property` commands.
-
-[Object Instance Properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#instance_properties),
-
-|name         |side-effect                   |
-|-------------|------------------------------|
-|`__proto__`  |access to function constructor|
-|`constructor`|access to function constructor|
-
-```js
-const f = () => {}
-{
-    const c = f.constructor
-    const g = c(`console.log('hello')`)
-    g() // side effect
-}
-{
-    const p = f.__proto__
-    const c = Object.getOwnPropertyDescriptor(p, 'constructor').value
-    const g = c(`console.log('hello')`)
-    g() // side-effect
-}
-```
-
-[Array Instance Properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#instance_properties).
-
-| |name    |side-effect|
-|-|--------|-----------|
-|0|`length`|no         |
-
-[Function Instance Properties](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function#instance_properties)
-
-| |name         |side-effect|run-time |
-|-|-------------|-----------|---------|
-| |`arguments`  |no         |error    |
-| |`caller`     |no         |error    |
-| |`displayName`|no         |         |
-| |`name`       |no         |error    |
-| |`prototype`  |no         |undefined|
-
-## Instance Method Call
-
-```js
-obj.property(parameters)
-obj.['property'](parameters)
-```
-
-It's translated into VM command `instance_method_call`:
-
-```rust
-struct InstanceMethodCall {
-    obj: Expression
-    property: String16
-    parameters: Array<Expression>
-}
-```
-
-**Note**: All known instance methods can't be used in `instance_property` command! Even if they don't have side effects.
-
-[Object Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object#instance_methods)
-
-|name                  |side-effect     |
-|----------------------|----------------|
-|`__defineGetter__`    |mutate          |
-|`__defineSetter__`    |mutate          |
-|`__lookupGetter__`    |'__proto__'     |
-|`__lookupSetter__`    |'__proto__'     |
-|`hasOwnProperty`      |no              |
-|`isPrototypeOf`       |no              |
-|`propertyIsEnumerable`|no              |
-|`toLocaleString`      |access to locale|
-|`toString`            |no              |
-|`valueOf`             |no              |
-
-[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array#instance_methods)
-
-|name                  |side-effect|notes   |
-|----------------------|-----------|--------|
-|`at`                  |no         |        |
-|`concat`              |no         |        |
-|`copyWith`            |no         |        |
-|`entries`             |yes        |iterator|
-|`every`               |no         |        |
-|`fill`                |yes        |mutate  |
-|`filter`              |no         |        |
-|`find`                |no         |        |
-|`findIndex`           |no         |        |
-|`findLast`            |no         |        |
-|`findLastIndex`       |no         |        |
-|`flat`                |no         |        |
-|`flatMap`             |no         |        |
-|`forEach`             |no         |        |
-|`includes`            |no         |        |
-|`indexOf`             |no         |        |
-|`join`                |no         |        |
-|`keys`                |yes        |iterator|
-|`lastIndexOf`         |no         |        |
-|`map`                 |no         |        |
-|`pop`                 |yes        |mutate  |
-|`push`                |yes        |mutate  |
-|`reduce`              |no         |        |
-|`reduceRight`         |no         |        |
-|`reverse`             |yes        |mutate  |
-|`shift`               |yes        |mutate  |
-|`slice`               |no         |        |
-|`some`                |no         |        |
-|`sort`                |yes        |mutate  |
-|`splice`              |yes        |mutate  |
-|`toReversed`          |no         |        |
-|`toSorted`            |no         |        |
-|`toSpliced`           |no         |        |
-|`unshift`             |yes        |mutate  |
-|`values`              |yes        |iterator|
-|`with`                |no         |        |
-
-[Function Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function#instance_methods)
-
-|name   |side-effect|notes            |
-|-------|-----------|-----------------|
-|`apply`|no         |`this` is ignored|
-|`bind` |no         |`this` is ignored|
-|`call` |no         |`this` is ignored|
-
-## At
-
-```js
-obj[42]
-obj[+index]
-```
-
-It's translated into VM command `at`:
-
-```rust
-struct InstanceMethodCall {
-    obj: Expression
-    index: Expression
-}
-```
-
-```js
-import m from './m.f.mjs'
-const a = [2, 3]
-export default {
-    "a": a[0],
-    // we don't know what is the type of `m` so we force it to be a `number` or `bigint`.
-    "b": a[+m]
-}
-```
-
-In `obj[index]`, `index` has to be a `number`. If we don't know what is `index`, `+` requires before `index`. It means the byte code for the expression inside the `[]` should be either the unary `+`, a number literal, or a string literal (excluding some strings). If it references an object, FS gives up. FS may try deeper analyses in the future, and type inference can help a lot.
-
-## Iterators
-
-Direct access to an object with the [`Iterator` protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) is not allowed in FunctionalScript.
-
-```ts
-type Value<T> = { done: true } | { done?: false, value: T }
-type Iterator<T> = {
-    next: () => Value<T>
-}
-```
-
-However, FunctionalScript allows access to objects with the `Iterable` protocol.
-
-```ts
-type Iterable<T> = {
-    [Symbol.iterator]: () => Iterator<T>
-}
-```
-
-For example, JS Array implements the `Iterable` protocol.
-
-If we need to implement support for [generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) in the FunctionalScript, the generator function has to be wrapped into `Iterable` interface. For example,
-
-```js
-// compilation error!
-const iterator = *() {
-    yield 4
-    yield 2
-}
-// ok
-const iterable = {
-    *[Symbol.iterator]() {
-        yield 4
-        yield 2
-    }
-}
-```

package/issues/lang/2340-operators.md

@@ -1,41 +0,0 @@
-# Operators
-
-|Type       |Operator |Priority   |
-|-----------|---------|-----------|
-|Comparison |`==`     |not allowed|
-|           |`!=`     |not allowed|
-|           |`===`    |1          |
-|           |`!==`    |1          |
-|           |`>`      |1          |
-|           |`>=`     |1          |
-|           |`<`      |1          |
-|           |`<=`     |1          |
-|Arithmetics|`+`      |1          |
-|           |`-`      |1          |
-|           |`*`      |1          |
-|           |`/`      |1          |
-|           |`%`      |1          |
-|           |unary `-`|1          |
-|           |unary `+`|1          |
-|           |`**`     |1          |
-|Bitwise    |`&`      |1          |
-|           |`\|`     |1          |
-|           |`^`      |1          |
-|           |`~`      |1          |
-|           |`<<`     |1          |
-|           |`>>`     |1          |
-|           |`>>>`    |1          |
-|Logical    |`&&`     |1          |
-|           |`\|\|`   |1          |
-|           |`??`     |1          |
-|           |`!`      |1          |
-|Conditional|`?:`     |1          |
-|Comma      |`,`      |not allowed|
-
-[Comma operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comma_operator) is useful only when we want to mutate. We have only one case where we can mutate an object; it's [let](./3320-let.md), and we would like to keep it as simple as possible to track life-time. So, NO for the `,` comma operator. 
-
-Depends on [default-export](./2110-default-export.md) and [undefined](./2310-undefined.md).
-
-For mutating operators, see [assignments](./3330-assignments.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_operators

package/issues/lang/2350-grouping.md

@@ -1,11 +0,0 @@
-# Grouping
-
-Group parts of an expression.
-
-```js
-export default (5)
-```
-
-Depends on [export-default](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Grouping

package/issues/lang/2360-built-in.md

@@ -1,81 +0,0 @@
-# Built-in Objects and Functions
-
-The built-in objects are special. We can call a function, like `Object.getOwnPropertyDescriptor()`, but not the `Object` or the function.
-
-https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects
-
-Some of the JS built-in objects and functions are "not allowed" in FS. It means, an FS compiler rejects code that contains "not allowed" objects and functions.
-
-## Object
-
-https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
-
-|Function                 |side-effect                |
-|-------------------------|---------------------------|
-|assign                   |mutate                     |
-|create                   |creates a special prototype|
-|defineProperties         |mutate                     |
-|defineProperty           |mutate                     |
-|entries                  |no                         |
-|freeze                   |mutate                     |
-|fromEntries              |no                         |
-|getOwnPropertyDescriptor |no                         |
-|getOwnPropertyDescriptors|no                         |
-|getOwnPropertyNames      |no                         |
-|getOwnPropertySymbols    |return symbols             |
-|getPrototypeOf           |return prototypes          |
-|groupBy                  |return null-property object|
-|hasOwn                   |no                         |
-|is                       |no                         |
-|isExtensible             |no                         |
-|isFrozen                 |no                         |
-|isSealed                 |no                         |
-|keys                     |no                         |
-|preventExtensions        |mutate                     |
-|seal                     |mutate                     |
-|setPrototypeOf           |mutate                     |
-|values                   |no                         |
-
-## Array
-
-https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
-
-|Function                 |side-effect|
-|-------------------------|-----------|
-|from                     |no         |
-|fromAsync                |?          |
-|isArray                  |no         |
-|of                       |no         |
-
-## BigInt
-
-|Function                 |side-effect|
-|-------------------------|-----------|
-|asIntN                   |no         |
-|asUintN                  |no         |
-
-## JSON
-
-|Function                 |side-effects|
-|-------------------------|-----------|
-|`isRawJSON`              |no         |
-|`parse`                  |no         |
-|`rawJSON`                |no         |
-|`stringify`              |no         |
-
-## Others
-
-|Function                 |side-effect|
-|-------------------------|-----------|
-|`decodeURI()`            |no         |
-|`decodeURIComponent()`   |no         |
-|`encodeURI()`            |no         |
-|`encodeURIComponent()`   |no         |
-|`eval()`                 |no         |
-
-|Property    |side-effect|
-|------------|-----------|
-|`Infinity`  |no         |
-|`isFinite()`|no         |
-|`isNaN()`   |no         |
-|`NaN`       |no         |

package/issues/lang/2410-identifier-property.md

@@ -1,9 +0,0 @@
-# Identifier Property
-
-```js
-export default {
-    a: 'hello',
-}
-```
-
-Depends on [default-import](./2130-default-import.md).

package/issues/lang/2420-line-comment.md

@@ -1,10 +0,0 @@
-# Line Comment
-
-```js
-// this is an object
-export default { "a": null }
-```
-
-Depends on [export-default](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#line_comments

package/issues/lang/2430-trailing-comma.md

@@ -1,13 +0,0 @@
-# Trailing Comma
-
-```js
-export default {
-    "b": [
-        "hello",
-    ],
-}
-```
-
-Depends on [default export](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Trailing_commas

package/issues/lang/2440-shorthand.md

@@ -1,8 +0,0 @@
-# Shorthand Property Names
-
-```js
-const a = [null]
-export default { a }
-```
-
-Depends on [identifier-property](./2410-identifier-property.md).

package/issues/lang/2450-destructuring.md

@@ -1,12 +0,0 @@
-# Destructuring Assignment
-
-```js
-const { "a": a, "%": [c, d] } = { "a": null, "%": [true, false] }
-export default {
-    "a": [a, c, d],
-}
-```
-
-Depends on [const](./2120-const.md) and [function parameters](./3120-parameters.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment.

package/issues/lang/3110-function.md

@@ -1,35 +0,0 @@
-# Function
-
-Parse a function that has no parameters and returns a constant.
-
-```js
-export default () => { return 6 }
-```
-
-Depends on [default export](./2110-default-export.md).
-
-See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions.
-
-## Recursive Functions
-
-```js
-const a = i => b(i + 3)  
-const b = i => i % 5 === 0 ? i : a(i)
-```
-
-```rust
-fn a(frame: Array<Any>, param: Array<Any>) {
-  let i = param[0];
-  let b = frame[1];
-  b(frame, &[i + 3]) 
-}
-fn b(frame: Array<Any>, param: Array<Any>) {
-  let i = param[0];
-  if (i % 5 === 0) {
-      i
-  } else {
-      let a = frame[0];
-      a(frame, &[i])
-  }
-}
-```

package/issues/lang/3120-parameters.md

@@ -1,9 +0,0 @@
-# Function Parameters
-
-Parse a function that has no parameters and returns a constant.
-
-```js
-export default (a, b) => { return [a, b] }
-```
-
-Depends on [function](./3110-function.md).

package/issues/lang/3130-body-const.md

@@ -1,12 +0,0 @@
-# Body Constants
-
-Parse a const definition in a function body; a const can be used within that body after it is defined.
-
-```js
-export default () => {
-    const x = 43
-    return [3, x]
-}
-```
-
-Depends on [function](./3110-function.md) and [const](./2120-const.md).

package/issues/lang/3220-let.md

@@ -1,11 +0,0 @@
-# Let statement
-
-Introducing `let` and `=`.
-
-```js
-export default () => {
-    let a = 0
-    a = 'Hello world!'
-    return a
-}
-```

package/issues/lang/3240-export.md

@@ -1,44 +0,0 @@
-# Non-default Export
-
-In FunctionalScript we use `export default`:
-
-```js
-export default 17
-```
-
-The main reason is that it's compatible with other module types, such as JSON and CommonJS.
-
-ECMAScript supports `export` of other non-default objects. We wouldn't have much reasons to support but systems as JSR doesn't really like `default` exports.
-
-To implement `export` we should change our definition of a module from `unknown` to
-
-```ts
-type Module = {
-    readonly [k in string]?: unknonwn
-    readonly default?: unknown
-}
-```
-
-Or, more strict version, which allows either `export` or `export default` but not both:
-
-```ts
-type Module = ExportMap | ExportDefault
-type ExportMap = Omit<{
-    readonly[k in string]: unknown
-}, 'default'>
-type DefaultExport = {
-    readonly default: unknown
-}
-```
-
-We don't need to change `import` for now if we implement `import * as X from ...`. For example
-
-```js
-// types/list/module.d.mjs
-export const map = ... 
-```
-
-```js
-import * as List from 'types/list/module.f.mjs'
-const { map } = List
-```