functionalscript 0.3.4 → 0.3.5

package/doc/LANGUAGE.md

@@ -1,255 +0,0 @@
-# FunctionalScript Programming Language
-
-Principles:
-
-- FunctionalScript VM should behaves the same way as a JavaScript VM,
-- Any unsupported feature should be reported at compile-time.
-
-## 1. Module Ecosystem
-
-FunctionalScript uses ESM conventions as a module ecosystem. For example,
-
-```js
-import thirdPartyModule from 'third-party-package/module'
-
-const result = thirdPartyModule.someFunction('hello')
-```
-
-## 2. Packages
-
-FunctionalScript uses a `package.json` file to define a package. This file is compatible with [Node.js `package.json`](https://nodejs.org/en/knowledge/getting-started/npm/what-is-the-file-package-json/).
-The preferred way to reference dependencies is to use a GitHub URL. These dependencies in a `package.json` file could look like this,
-
-```json
-{
-   // ...
-   "dependencies": {
-      "third-party-package": "github:exampleorg/thirdpartypackage"
-   }
-   // ...
-}
-```
-
-**Note:** this repository is also a FunctionalScript package, and it can be used as a library. To install this package, use
-
-```
-npm install -S github:functionalscript/functionalscript
-```
-
-## 3. Module Structure
-
-A module is a file with the `.js` extension. It contains three parts: references to other modules, definitions, and exports. For example
-
-`./first.f.mjs`
-```js
-// 1. references
-import math from 'math'
-
-// 2. definitions
-const myConst = 42
-// addition(a)(b) = a + b
-const addition = a => b => a + b
-const add42 = addition(42)
-const _10digitsOfPi = math.calculatePi(10)
-
-// 3. exports
-export default {
-   addition,
-   add42,
-   _10digitsOfPi,
-}
-```
-
-`./second.f.mjs`
-```js
-// 1. references
-import first from './first.f.mjs'
-
-// 2. definitions
-const _42plus7 = first.add42(7)
-
-// 3. exports
-export default {
-   _42plus7,
-}
-```
-
-## 4. References To Other Modules
-
-The format of references is `import ANYNAME from 'PATH_TO_A_MODULE'`. For example,
-
-```js
-import math from 'math'
-import algebra from 'math/algebra'
-import localFile from '../some-directory/some-file.f.mjs'
-```
-
-## 5. Definitions
-
-The format of definitions is `const NAME = EXPRESSION`, where the `EXPRESSION` is a subset of [JavaScript expressions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Expressions_and_Operators).
-
-```js
-const myConst = 42
-const functionDouble = a => a * 2
-const structure = { name: "John", surname: "Smith" }
-const array = [1, 2, 3]
-const nestedStructure = {
-   address: null,
-   serialNumber: "123-45-78",
-   sum: 14 + myConst + functionDouble(4),
-   moreInfo: {
-      name: "Ivan",
-      surname: "Terrible",
-   }
-}
-```
-
-See [Expressions](#7-Expressions).
-
-### 6. Exports
-
-The format of exports is `export default { A_LIST_OF_EXPORTED_DEFINITIONS }`. There should be only one `export default` at
-the end of a FunctionalScript file. For example,
-
-```js
-export default {
-   nestedStructure,
-   array,
-   structure,
-}
-```
-
-## 7. Expressions
-
-Expressions could fall under these categories:
-
-- Literals:
-  - Number Literals, e.g. `0`, `3.14`, `4e8`
-  - Boolean Literals: `true` or `false`
-  - A `null` Literal
-  - An `undefined` Literal
-  - String Literals, e.g. `"Hello world!"`
-- Complex Structures
-  - Arrays, e.g. `[2, 5]`
-  - Objects, e.g. `{ a: "Hello", b: "world!" }`
-  - Arrow functions, e.g. `x => x * 2`
-- Operators
-  - Comparison Operators: `===`, `!==`, `>`, `>=`, `<`, `<=`
-  - Arithmetic Operators: `+`, `-`, `*`, `/`, `%`, `**`
-  - Bitwise Operators: `&`, `|`, `^`, `~`, `<<`, `>>`, `>>>`
-  - Logical Operators: `&&`, `||`, `!`, `??`
-  - Conditional Operator, e.g. `condition ? val1 : val2`
-  - Template Literals, e.g. `string ${expression}`
-  - `typeof`
-  - Relations Operators: `in`, `instanceof`.
-  - Member Operators: `.`, `[]`.
-
-**Note:** the `.` member operator has prohibited property names, such as `constructor` and `push`. To access such properties, it's recommended to use the
-[Object.getOwnPropertyDescriptor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect/getOwnPropertyDescriptor) function.
-`[]` accepts only numbers. For example `+'0'`
-
-## 8. Arrow Functions
-
-An arrow function is also known as [a lambda function](https://en.wikipedia.org/wiki/Anonymous_function).
-The format of an arrow function is `ARGUMENT_NAME => FUNCTION_BODY`. An arrow function must have either a single argument or no arguments at all. For example
-
-```js
-x => x * 2
-a => a + 4
-s => `template literal ${s}`
-a => b => a + b // an arrow functions that returns another arrow functions.
-() => 'hello' // an arrow function with no arguments
-```
-
-A function body is either an expression or a block statement. A block statement format is `{ A_LIST_OF_STATEMENTS }`. For example
-
-```js
-// a function with one argument and a block statement
-const f = x => {
-   const a = 2 + x
-   const r = a + 4
-   return r
-}
-```
-
-## 9. Statements
-
-`{ A_LIST_OF_STATEMENTS }` is one or many statements separated by the newline control character. One of these statements mentioned earlier was [definition](#5-Definitions), also known as a [const](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) statement. The other statements are described below.
-
-### 9.1. Let
-
-[Let](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let) declares a local mutable alias for immutable objects. For example
-
-```js
-let x = [5]
-// you can assign another immutable object to the alias at any time.
-x = [3, 4]
-//but you can't change the properties of the immutable object.
-x[0] = 3 // < invalid
-//let aliases can not be referenced from another arrow function.
-const f = () => x // < invalid
-```
-
-### 9.2. Return
-
-[Return](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/return)
-
-### 9.3. If...Else
-
-[If...Else](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/if...else)
-
-### 9.4. Switch
-
-[Switch](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/switch)
-
-### 9.5. Throw
-
-[Throw](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/throw). FunctionalScript allows to throw exceptions, but the language has no syntax to catch them. Developers should only use the 'throw' statement in non-recoverable situations. Throwing an exception could be compared to [panic in Rust](https://doc.rust-lang.org/std/macro.panic.html).
-
-### 9.6. While
-
-[While](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/while)
-
-### 9.7. Block
-
-[Block](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/block)
-
-## 10. Generators
-
-For compatibility reason, FunctionalScript allows to create generators as implementation of `[Symbol.iterator]` function. However, it doesn't allow to read the `[Symbol.iterator]` property. For example
-
-This code is allowed
-
-```js
-/** @type {<T>(list: List<T>) => Iterable<T>} */
-const iterable = list => ({
-    *[Symbol.iterator]() {
-        let i = list
-        while (true) {
-            const r = next(i)
-            if (r === null) { return }
-            yield r.first
-            i = r.tail
-        }
-    }
-})
-```
-
-The following code is not allowed, because `iterator` is a mutated object by design in JavaScript.
-
-```js
-const it = [0, 1, 2][Symbol.iterator] //< compilation error.
-```
-
-Use `Iterable` instead of `Iterator`.
-
-```js
-const x = () => {
-    const a = [0, 1, 2] // iterable
-    let sum = 0;
-    for (let i in a) {
-        sum = sum + i
-    }
-    return sum;
-}
-```

package/doc/README.md

@@ -1,61 +0,0 @@
-# Documentation
-
-FunctionalScript files have `.f.mjs` file extensions because it's using the ES module system.
-
-## 1. Language
-
-### 1.1. Exports
-
-```js
-export default 'Hello world!'
-```
-
-```js
-export default { a: 'hello', b: 42 }
-```
-
-```js
-export default x => x * x
-```
-
-### 1.2. Reference Another Module
-
-#### 1.2.1. Local File
-
-```js
-import x from './folder/main.f.mjs'
-```
-
-### 1.2.2. External Module
-
-Run `npm install -D github:USER/REPO`
-
-```js
-import x from `REPO/DIR/FILE.f.mjs`
-```
-
-### 1.3. Functions
-
-```js
-const f = x => x * x
-const fResult = f(42)
-
-const plus = a => b => a + b
-const plusResult = plus(a)(b)
-
-const sum = ar => ar.reduce((a, i) => a + i, 0)
-const sumResult = sum([1, 2, 3])
-```
-
-## 2. Advanced
-
-### 2.1. Generators
-
-```js
-const range5 = {*[System.iterator]() {
-    yield 0
-    yield 1
-    yield 2
-    yield 3
-}}
-```

package/doc/byte-code.md

@@ -1,59 +0,0 @@
-# Byte Code
-
-This format is designed for fast and straightforward serialization and doesn't depend on a particular VM implementation.
-
-**Requirements:** 
-- VM serializer/deserializer should be very simple.
-    - string: UTF16
-    - number: in a binary format
-    - bigint: in a binary format
-    - len: u32
-- the byte code doesn't know anything about importing modules or I/O functions.
-- the byte code shouldn't contain syntax sugar.
-- serialized in a byte array so we can save it into a file. One byte is one unit.
-- least-significant byte first.
-
-```rust
-struct Array<T> {
-    len: u32,
-    array: [T; self.len],
-}
- 
-type String = Array<u16>;
-
-// LSB first.
-type BigUInt = Array<u64>;
-
-type Object = Array<(String, Any)>;
-
-// This is the main structure for serialization.
-type Code = Array<u8>;
-
-struct Function {
-    length: u32
-    code: Code
-}
-
-// This structure is not for serialization because
-// a serialized module should resolve all imports.
-struct Module {
-    import: Array<String>
-    code: Code
-}
-```
-
-|format|any            |Tag|                       |
-|------|---------------|---|-----------------------|
-|JSON  |null           | 00|                       |
-|      |number         | 01|u64                    |
-|      |false          | 02|                       |
-|      |true           | 03|                       |
-|      |string         | 04|String                 |
-|      |object         | 05|Object                 |
-|      |array          | 06|Array<Any>             |
-|DJS   |ref            | 07|u32                    |
-|      |positive_bigint| 08|BigUInt                |
-|      |negative_bigint| 09|BigUInt                |
-|FJS   |function       | 0A|Function               |
-|      |arg_ref        | 0B|u32                    |
-|      |undefined      | 0C|                       |

package/doc/fa.md

@@ -1,174 +0,0 @@
-# FA
-
-```
-F ::= A 'hello'
-F ::= A 'help'
-```
-
-## Classic FA
-
-```
-S0 ::= A 'h'
-S1 ::= S0 'e'
-S2 ::= S1 'l'
-S3 ::= S2 'l'
-F ::= S3 'o'
-
-X0 ::= A 'h'
-X1 ::= X0 'e'
-X2 ::= X1 'l'
-F ::= X2 'p'
-```
-
-## DFA
-
-```
-{S0,X0} = A 'h'
-{S1,X1} ::= {S0,X0} 'e'
-{S2,X2} ::= {S1,X1} 'l'
-S3 ::= {S2,X2} 'l'
-F ::= {S2,X2} 'p'
-F ::= S3 'o'
-
-P0 = A 'h'
-P1 ::= P0 'e'
-P2 ::= P1 'l'
-S3 ::= P2 'l'
-F ::= P2 'p'
-F ::= S3 'o'
-```
-
-## Tokenizer FA
-
-```
-T ::= I 'true'  // T0, T1, T2
-F ::= I 'false' // F0, F2, F2, F3
-N ::= I 'null'  // N0, N1, N2
-Id ::= I letter
-Id ::= Id letter
-Id ::= Id digit
-```
-
-## Tokenizer DFA
-
-```
-{T0,Id} = I 't'
-{T1,Id} = {T0,Id} 'r'
-Id = {T0,Id} letter(except 'r')
-Id = {T0,Id} digit
-
-{a..b}{c..d}{e..f}
-```
-
-```js
-const t0 = [[init, one('t')]]
-const t1 = [[t0, one('r')]]
-const t2 = [[t1, one('u')]]
-const t = [[t2, one('e')]]
-
-const id = [
-    [init, letter]
-    [() => id, letter]
-    [() => id, digit]
-]
-
-const dfa = ([t, f, n, id]) => ?
-```
-
-## Set
-
-```js
-const letter = byteSet(['_', '$', ['a', 'z'], ['A', 'Z']])
-```
-
-Letters and digits
-
-|      |            |
-|------|------------|
-|`$`   |`0x24`      |
-|`0..9`|`0x30..0x39`|
-|`A..Z`|`0x41..0x5A`|
-|`_`   |`0x5F`      |
-|`a..z`|`0x61..0x7A`|
-
-## Bit set
-
-For a byte, it is an array of 8 uint32, bigint (0..2^256-1), or string of 16 characters.
-
-### 16 bit set.
-
-It can use an intermediate state.
-
-|   |       |        |
-|---|-------|--------|
-|`2`|`4`    |`$`     |
-|`3`|`..9`  |`0..9`  |
-|`4`|`1..`  |`A..O`  |
-|`5`|`..A,F`|`P..Z,_`|
-|`6`|`1..`  |`a..o`  |
-|`7`|`..A`  |`p..z`  |
-
-```js
-const init = [
-   _,  _, i2,  _,
-  i4, i5, i4, i7,
-   _,  _,  _,  _,
-   _,  _,  _,  _]
-
-const i2 = [
-   _,  _,  _,  _,
-  id,  _,  _,  _,
-   _,  _,  _,  _,
-   _,  _,  _,  _]
-
-const i3 = [
-  id, id, id, id,
-  id, id, id, id,
-  id, id,  _,  _,
-   _,  _,  _,  _]
-
-const i4 = [
-   _, id, id, id,
-  id, id, id, id,
-  id, id, id, id,
-  id, id, id, id]
-
-const i5 = [
-  id, id, id, id,
-  id, id, id, id,
-  id, id, id,  _,
-   _,  _,  _, id]
-
-const i7 = [
-  id, id, id, id,
-  id, id, id, id,
-  id, id, id,  _,
-   _,  _,  _,  _]
-
-const id = [
-   _,  _, i2, i3,
-  i4, i5, i4, i7,
-   _,  _,  _,  _,
-   _,  _,  _,  _]
-```
-
-```js
-const init =
-  000_000_001_000
-  010_011_100_101
-  000_000_000_000
-  000_000_000_000
-
-const i = [
-  // 1
-  0000_1000_0000_0000,
-  // 2
-  1111_1111_1100_0000,
-  // 3
-  0111_1111_1111_1111,
-  // 4
-  1111_1111_1110_0001,
-  // 5
-  1111_1111_1110_0000,
-]
-```

package/doc/predefined.md

@@ -1,143 +0,0 @@
-# Predefined Object And Properties
-
-## Global Objects
-
-Global objects. Global objects can't be assigned to something `const r = Object`. They can only be used as namespaces `Object.getOwnProperties()`.
-
-### Value properties
-
-- [x] `Infinity`
-- [x] `NaN`
-- [ ] `undefined`
-- [ ] `globalThis`
-
-### Function properties
-
-- [ ] `eval`
-- [x] `isFinite()`
-- [x] `isNan()`
-- [x] `parseFloat()`
-- [x] `parseInt()`
-- [ ] `encodeURI()`
-- [ ] `encodeURIComponent()`
-- [ ] `decodeURI()`
-- [ ] `decodeURIComponent()`
-
-### Fundamental objects
-
-- [x] `Object`. For example `Object.entries`, `Object.fromEntries`.
-- [ ] `Function`
-- [ ] `Boolean`
-- [ ] `Symbol`
-
-### Error objects
-
-- [ ] `Number`
-- [ ] `BigInt`
-- [ ] `Math`
-- [ ] `Date`
-
-### Text processing
-
-- [ ] `String`
-- [ ] `RegExp`
-
-### Indexed collections:
-
-- [x] `Array`. For example `x instanceof Array`
-- [ ] `Int8Array`
-- [ ] `UInt8Array`
-- [ ] `UInt8ClampedArray`
-- [ ] `Int16Array`
-- [ ] `UInt16Array`
-- [ ] `Int32Array`
-- [ ] `UInt32Array`
-- [ ] `Float32Array`
-- [ ] `Float64Array`
-- [ ] `BigInt64Array`
-- [ ] `BigUint64Array`
-
-### Keyed collections:
-
-- [ ] `Map`
-- [ ] `Set`
-- [ ] `WeakMap`
-- [ ] `WeakSet`
-
-### Structured data:
-
-- [ ] `ArrayBuffer`
-- [ ] `SharedArrayBuffer`
-- [ ] `Atomics`
-- [ ] `DataView`
-- [x] `JSON`. For example `JSON.stringify`
-
-### Control abstraction objects
-
-- [ ] `Promise`
-- [ ] `Generator`
-- [ ] `GeneratorFunction`
-- [ ] `AsyncFunction`
-- [ ] `AsyncGeneratorFunction`
-
-### Reflection
-
-- [ ] `Reflect`
-- [ ] `Proxy`
-
-### Internalization
-
-- [ ] `Intl`
-
-### WebAssembly
-
-- [ ] `WebAssembly`
-- [ ] `WebAssembly.Module`
-- [ ] `WebAssembly.Instance`
-- [ ] `WebAssembly.Memory`
-- [ ] `WebAssembly.Table`
-- [ ] `WebAssembly.CompileError`
-- [ ] `WebAssembly.LinkError`
-- [ ] `WebAssembly.RuntimeError`
-
-## Prohibited Properties
-
-Allowed types:
-
-- object `{}`
-  - `null` has no properties
-- array `[]`
-- number `-3`
-- bigint `42n`
-- string `"xx"`
-- boolean `true`
-- function `x => x * x`
-- `undefined` has no properties
-
-### Object
-
-https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
-
-- [ ] ! `constructor`. The property can create a new function. For example
-  ```js
-  const f = (() => null).constructor('a', 'return a * a')
-  ```
-- [ ] deprecated `__proto__`
-- [ ] ! deprecated `__defineGetter__`. The property can mutate an object.
-- [ ] ! deprecated `__defineSetter__`. The property can mutate an object.
-- [ ] deprecated `__lookupGetter__`
-- [ ] deprecated `__lookupSetter__`
-
-### Array
-
-These properties can mutate an array:
-
-- [ ] ! `copyWithin`.
-- [ ] ! `fill`
-- [ ] ! `pop`
-- [ ] ! `push`
-- [ ] ! `reverse`
-- [ ] ! `shift`
-- [ ] ! `sort`
-- [ ] ! `splice`
-- [ ] ! `unshift`

package/doc/proposals.md

@@ -1,21 +0,0 @@
-# ECMAScripts Proposals
-
-ECMAScript proposals that may affect FunctionalScript
-
-- Type Annotations: https://github.com/tc39/proposal-type-annotations
-  ```js
-  const add = (a: bigint) => (b: bigint) => a + b
-  ```
-- Deeply Immutable Record and Tuples: https://github.com/tc39/proposal-record-tuple
-  ```js
-  const r = #{ x: 4, y: "s" }
-  const t = #[5, "hello"] 
-  ```
-  Because these types are deeply immutable and the equality operator '===' works as deep equality, it's a good candidate for content-addressable type system.
-- Pipeline operator https://github.com/tc39/proposal-pipeline-operator
-  ```js
-  const double = a => a + a
-  const munis1 = a => a - 1
-  const f = a => a |> double(%) |> minus1(%) 
-  ```
-  I, Sergey, still prefer F# pipeline operator and strongly believe that it's possible to have both syntax in the language.