functionalscript 0.0.252 → 0.0.265

package/README.md

@@ -3,157 +3,179 @@
 FunctionalScript is a pure functional programming language and a strict subset of 
 [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript)/[JavaScript](https://en.wikipedia.org/wiki/JavaScript). It's inspired by 
 
-- [JSON](https://en.wikipedia.org/wiki/JSON), as a subset of JavaScript; FunctionalScript is a superset of JSON.
-- [asm.JS](https://en.wikipedia.org/wiki/Asm.js)/[WebAssembly](https://en.wikipedia.org/wiki/WebAssembly), as a subset of JavaScript;
+- [JSON](https://en.wikipedia.org/wiki/JSON) as a subset of JavaScript. JSON is also a subset of FunctionalScript.
+- [asm.JS](https://en.wikipedia.org/wiki/Asm.js)/[WebAssembly](https://en.wikipedia.org/wiki/WebAssembly), as a subset of JavaScript.
 - [TypeScript](https://en.wikipedia.org/wiki/TypeScript), as a superset of JavaScript.
 
+Create a new FunctionalScript repository on GitHub [here](https://github.com/functionalscript/template/generate).
+
 Try FunctionalScript [here](https://functionalscript.com/).
 
-Create a new FunctionalScript repository on GitHub [here](https://github.com/functionalscript/template/generate).
+## 1. Design Principles
 
-One of the main challenges is how to make a pure functional language when ES6 TCO is not supported by Chrome and Firefox.
-A workaround for this problem is to use `let` for renaming objects.
+In FunctionalScript:
 
-## Install FunctionalScript As A Library
+- Any module is a valid JavaScript module
+- Code should not have [side-effects](https://en.wikipedia.org/wiki/Side_effect_(computer_science)). Any JavaScript statement, expression, or function which has a side effect is not allowed in FunctionalScript. There are no exceptions to this rule, such as `unsafe` code which can be found in Rust, C#, and other languages.
+- A module can't depend on non FunctionalScript module. 
+- It also has no standard library, only a safe subset of standard JavaScript API can be used without referencing other modules.
 
-```
-npm install -S github:functionalscript/functionalscript
-```
+## 2. Outlines
 
-##  JSON
+### 2.1. Module Ecosystem
+
+FunctionalScript uses [CommonJS](https://en.wikipedia.org/wiki/CommonJS) conventions as a module ecosystem. For example,
 
 ```js
-jsonFile = expression
-expression = primitive | array | objects
-primitive = 'true' | 'false' | 'null' | number | string
-array = '[' (() | items) ']'
-items = expression (() | ',' items)
-object = '{' (() | properties) '}'
-properties = propertyId ':' expression (() | ',' properties)
-propertyId = string
+const thirdPartyModule = require('third-party-package/module')
+
+const result = thirdPartyModule.someFunction('hello')
 ```
 
-## Stage 0
+### 2.2. Packages
 
-This stage can be used as an intermediate-code for VMs.
+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 prefered way to refence dependencies is to use a GitHub URL. These dependencies in a `package.json` file could look like this,
 
-```js
-fjsFile = expression
-expression = primitive | array | object | func | id | propertyAccessor
-func = ('()' | id) '=>' body
-body = '{' statements 'return' expression ';' '}'
-statements = () | (statement statements)
-statement = decl | ifStatement
-decl = `const` id `=` expression `;`
-ifStatement = `if` `(` expression `)` body
-propertyAccessor = expression `[` expression `]`
-call = expression `(` ( expression | ()) `)`
+```json
+{
+   ...
+   "dependencies": {
+      "third-party-package": "github:exampleorg/thirdpartypackage"
+   }
+   ...
+}
 ```
 
-### Stage 0.1. Node.js
+**Note:** this repository is also a FunctionalScript package, and it can be used as a library. To install this package, use
 
-```js
-nodeFile = statements 'module.exports' '=' expression ';'
+```
+npm install -S github:functionalscript/functionalscript
 ```
 
-### Stage 0.2. 
+### 2.3. Module Structure
 
-#### Operators
+A module is a file with the `.js` extention. It contains three parts: references to other modules, definitions, and exports. For example
 
+`./first.js`
 ```js
-expression = ... | 'undefined' | groupingOperator | binaryOperatorExpression | unaryOperator | conditionalOperator
-groupingOperator = '(' expression ')'
-binaryOperatorExpression = expression binaryOperator expression
-binaryOperator = comparisonOperator | arithmeticOperator | bitwiseOperator | logicalOperators | '??'
-comparisonBinaryOperator = '===' | '!==' | '>' | '<' | '>=' | '<='
-arithmeticBinaryOperator = '+' | '-' | '*' | '/' | '%' | '**'
-bitwiseBinaryOperator = '&' | '|' | '^' | '<<' | '>>' | '>>>'
-logicalBinaryOperator = '&&' | '||'
-unaryOperator = '-' | '~' | '!'
+// 1. references
+const math = require('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
+module.exports = {
+   addition,
+   add42,
+   _10digitsOfPi,
+}
 ```
 
-Note: the syntax should be fixed to reflect operator precedents.
+`./second.js`
+```js
+// 1. references
+const first = require('./first.js')
+
+const _42plus7 = first.add42(7)
+```
 
-No `==`, `!=`, `=...` operators.
+### 2.4. References To Other Modules
 
-#### Function Expression
+The format of references is `const ANYNAME = require('PATH_TO_A_MODULE')`. For example,
 
 ```js
-func = ('()' | id) '=>' (('{' statements 'return' expression ';' '}') | expression)
+const math = require('math')
+const algebra = require('math/algebra')
+const localFile = require('../some-directory/some-file.js')
 ```
 
-#### PropertyAccessor
+### 2.5. Definitions
 
-```js
-propertyAccessor = expression (('[' expression ']') | ('.' id))
-```
+The format of defintions 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
-propertyId = string | id
+const myConst = 42
+const functionDouble = a => a * 2
+const structure = { name: "John", surname: "Smith" }
+const array = [1, 2, 3]
+const nestedStructure = { 
+   address: undefined, 
+   serialNumber: "123-45-78", 
+   sum: 14 + myConst + functionDouble(4),
+   moreInfo: { 
+      name: "Ivan",
+      surname: "Terrible",
+   } 
+}
 ```
 
-#### BigInt
+See [3. Expressions](#3-Expressions).
 
-For example `42n`.
+### 2.6. Exports
 
-#### Additional Operators
+The format of exports is `module.exports = { A_LIST_OF_EXPORTED_DEFINITIONS }`. There should be only one `module.exports` at
+the end of a FunctionalScript file. For example,
 
 ```js
-typeOfOperator = 'typeof' expression
-inOperator = expression 'in' expression
+module.exports = {
+   nestedStructure,
+   array,
+   structure,
+}
 ```
 
-### Stage 0.3. Syntax sugar
-
-Hex, binary and octal literals
-Functions with multiple parameters.
-Spread syntax. For example `...object`.
-Destructing assignments. For example `const {a,b} = exp;`, `const [a, b] = exp`.
-Property Id expression `{ [exp]: exp }`.
-Allow no semicolons.
-Optional comma in arrays and objects.
-Template literals ``const r= `onst r = ${exp}`;``.
-An `if` statement `if (exp) { ... return exp }`
-Multiline strings 
+## 3. 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 prohibitted property names, such as `constructor` and `push`. To access such properties, it's recommeded to use the `Object.getPropertyDescriptor` function.
+
+## 4. 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}`
+() => '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
-'sss\
-   wwww'
+// a function with one argument and a block statement
+const f = x => {
+   const a = 2 + x
+   const r = a + 4
+   return r
+}
 ```
-Regular expressions.
-
-## Stage 1
-
-Typing using [JSDoc](https://jsdoc.app/) and TypeScript types.
-
-## Stage 2
-
-Mutable types with exclusive ownership (similar to Rust mutability).
-
-- `let`, `for`, `while` etc.
-  Note: `let` can work as an object name reuse. 
-  In this case, `let` objects can't be used in nested functions. It means we can't reference `let` object.
-  ```js
-  let x = 5 // ok
-  f(x)
-  x = 'hello!' // ok
-  f(x)
-  const r = () => {
-     return x // compilation error
-  }
-  ```
-  Translated into
-  ```js
-  const x0 = 5
-  f(x0)
-  const x1 = 'hello!'  
-  f(x1)
-  ```
-- Generators `function*(){  ... yield ... }`.
-- Async `async () => f(await exp())`.
-- hopefully, we will have [ES pipe operator](https://tc39.es/proposal-pipeline-operator/) at this time.
-- [pattern matching](https://github.com/tc39/proposal-pattern-matching)
-
-Controversial ideas: 
-
-- Import and export `import x from "..."`, `export const x = ...`, `export default = ` e.t.c. This may break `new Function` runners. 
-- Functional-TypeScript as a subset of TypeScript. Note: FunctionalScript doesn't require an additional build step in contrast to TypeScript.

package/commonjs/README.md

@@ -52,4 +52,8 @@ type BuildState<M> = {
 }
 
 const getOrBuild: <M>(buildConfig: BuildConfig<M>) => readonly[ModuleState, M];
+
+//
+
+
 ```

package/commonjs/build/index.js

@@ -0,0 +1,62 @@
+const package_ = require('../package')
+const module_ = require('../module')
+const function_ = require('../module/function')
+const { todo } = require('../../dev')
+
+/**
+ * @template M
+ * @typedef {{
+ *  readonly pagkageGet: package_.Get
+ *  readonly moduleMapInterface: module_.MapInterface<M>
+ *  readonly moduleId: module_.Id
+ *  readonly moduleMap: M
+ * }} Config
+ */
+
+/** 
+ * @template M
+ * @typedef {readonly[module_.State, M]} Result 
+ */
+
+/** 
+ * @type {(packageGet: package_.Get) =>
+ *  <M>(moduleMapInterface: module_.MapInterface<M>) =>
+ *  (compile: function_.Compile) =>
+ *  (moduleId: module_.Id) =>
+ *  (moduleMap: M) =>
+ *  Result<M>
+ * } 
+ */
+const getOrBuild = packageGet => moduleMapInterface => compile => moduleId => moduleMap => {
+    const moduleIdStr = module_.idToString(moduleId)
+
+    /** @type {() => Result<typeof moduleMap>} */
+    const notFound = () => [['error', ['file not found']], moduleMap]
+    
+    /** @type {(e: module_.Error) => Result<typeof moduleMap>} */
+    const error = e => {
+        /** @type {module_.State} */
+        const state = ['error', e]
+        moduleMapInterface.insert(moduleIdStr)(state)
+        return [state, moduleMap]
+    }
+
+    const m = moduleMapInterface.at(moduleIdStr)(moduleMap)
+    if (m !== undefined) { return [m, moduleMap] }
+    
+    const p = packageGet(moduleId.packageId)
+    if (p === undefined) { return notFound() }
+    
+    const source = p.file(moduleId.path.join('/'))
+    if (source === undefined) { return notFound() }
+    
+    const compileResult = compile(source)
+    if (compileResult[0] === 'error') { return error(['compilation error', compileResult[1]]) }
+    
+    return todo()
+}
+
+module.exports = {
+    /** @readonly */
+    getOrBuild,
+}

package/commonjs/module/function/index.js

@@ -0,0 +1,21 @@
+/**
+ * An IO interface for creating and running module functions.
+ */
+
+const result = require('../../../types/result')
+
+/** @typedef {<M>(require: Require<M>) => (prior: M) => Result<M>} Function */
+
+/**
+ * @template M
+ * @typedef {readonly[result.Result<unknown, unknown>, M]} Result 
+ */
+
+/**
+ * @template M
+ * @typedef {(path: string) => (prior: M) => Result<M>} Require
+ */
+
+/** @typedef {(source: string) => result.Result<Function, unknown>} Compile */
+
+module.exports = {}

package/commonjs/module/index.js

@@ -3,17 +3,17 @@ const object = require('../../types/object')
 /**
  * @template M
  * @typedef {{
- *  readonly at: (moduleId: string) => (moduleMap: M) => ModuleState | undefined
- *  readonly insert: (moduleId: string) => (moduleState: ModuleState) => (moduleMap: M) => M
- * }} ModuleMapInterface
+ *  readonly at: (moduleId: string) => (moduleMap: M) => State | undefined
+ *  readonly insert: (moduleId: string) => (moduleState: State) => (moduleMap: M) => M
+ * }} MapInterface
  */
 
 /** 
  * @typedef {|
  *  readonly['ok', Module] | 
- *  readonly['error', ModuleError] | 
+ *  readonly['error', Error] | 
  *  readonly['building']
- * } ModuleState 
+ * } State 
  */
 
 /**
@@ -25,11 +25,24 @@ const object = require('../../types/object')
 
 /** 
  * @typedef {|
- *  'file not found' | 
- *  'compile error' | 
- *  'runtime error' | 
- *  'circular reference'
- * } ModuleError
+ *  ['file not found'] | 
+ *  ['compilation error', unknown] | 
+ *  ['runtime error'] | 
+ *  ['circular reference']
+ * } Error
  */
 
-module.exports = {}
+/**
+ * @typedef {{
+ *  readonly packageId: string
+ *  readonly path: readonly string[]
+ * }} Id
+ */
+
+/** @type {(id: Id) => string} */
+const idToString = ({ packageId, path }) => `${packageId}/${path.join('/')}`
+
+module.exports = {
+    /** @readonly */
+    idToString,
+}

package/commonjs/package/index.js

@@ -1,13 +1,11 @@
 const json = require('../../json')
-const dep = require('./dependencies')
-const object = require('../../types/object')
-const run = require('../run')
+const dependencies = require('./dependencies')
 
 /** 
  * @typedef {{
  *  readonly name: string
  *  readonly version: string
- *  readonly dependencies?: dep.DependenciesJson
+ *  readonly dependencies?: dependencies.DependenciesJson
  * }} PackageJson 
  */
 
@@ -16,7 +14,7 @@ const isPackageJson = j => {
     if (!json.isObject(j)) { return false }
     if (typeof j.name !== 'string') { return false }
     if (typeof j.version !== 'string') { return false }
-    if (!dep.isDependenciesJson(j.dependencies)) { return false }
+    if (!dependencies.isDependenciesJson(j.dependencies)) { return false }
     return true
 }
 
@@ -27,7 +25,7 @@ const isPackageJson = j => {
  * }} Package
  */
 
-/** @typedef {(packageId: string) => Package | undefined} PackageGet */
+/** @typedef {(packageId: string) => Package | undefined} Get */
 
 module.exports = {
     /** @readonly */

package/io/commonjs/index.js

@@ -1,12 +1,14 @@
 const { tryCatch } = require('../result')
 const { unwrap } = require('../../types/result')
-const run = require('../../commonjs/run')
+const moduleFunction = require('../../commonjs/module/function')
 
-/** @type {(f: Function) => run.Module} */
+/** @type {(f: Function) => moduleFunction.Function} */
 const build = f => immutableRequire => mutableData => {
     /** @type {(path: string) => unknown} */
     const mutableRequire = path => {
         const [result, data] = immutableRequire(path)(mutableData)
+        // Side effect: setting a variable from a nested function (closure) 
+        // is not allowed in FunctionalScript.
         mutableData = data
         return unwrap(result)
     }
@@ -18,8 +20,9 @@ const build = f => immutableRequire => mutableData => {
     return [result, mutableData]
 }
 
-/** @type {run.Compile} */
+/** @type {moduleFunction.Compile} */
 const compile = source => 
+    // Side effect: a `Function` constructor is not allowed in FunctionalScript.
     tryCatch(() => build(Function('module', 'require', `"use strict";${source}`)))
 
 module.exports = {

package/io/commonjs/test.js

@@ -1,5 +1,5 @@
 const _ = require('.')
-const run = require('../../commonjs/run')
+const run = require('../../commonjs/module/function')
 
 // ok:
 {

package/io/result/index.js

@@ -2,6 +2,7 @@ const result = require('../../types/result')
 
 /** @type {<T>(f: () => T) => result.Result<T, unknown>} */
 const tryCatch = f => {
+    // Side effect: `try catch` is not allowed in FunctionalScript.
     try {
         return result.ok(f())
     } catch (e) {
@@ -12,4 +13,4 @@ const tryCatch = f => {
 module.exports = {
     /** @readonly */
     tryCatch,
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.0.252",
+  "version": "0.0.265",
   "description": "FunctionalScript is a functional subset of JavaScript",
   "main": "index.js",
   "scripts": {
@@ -19,7 +19,9 @@
     "functional-programming",
     "closure",
     "pure-functional",
-    "typescript"
+    "typescript",
+    "programming-language",
+    "lazy-evaluation"
   ],
   "bugs": {
     "url": "https://github.com/functionalscript/functionalscript/issues"

package/commonjs/run/index.js

@@ -1,17 +0,0 @@
-const result = require('../../types/result')
-
-/** @typedef {<T>(req: Require<T>) => (prior: T) => ModuleResult<T>} Module*/
-
-/**
- * @template T 
- * @typedef {readonly[result.Result<unknown, unknown>, T]} ModuleResult 
- */
-
-/**
- * @template T 
- * @typedef {(path: string) => (prior: T) => ModuleResult<T>} Require
- */
-
-/** @typedef {(source: string) => result.Result<Module, unknown>} Compile */
-
-module.exports = {}