functionalscript 0.1.599 → 0.1.601

package/.github/workflows/npm-publish.yml

@@ -29,9 +29,11 @@ jobs:
       - run: npm run index
       - run: npm run tscp
       - run: npm publish
+        continue-on-error: true
         env:
           NODE_AUTH_TOKEN: ${{secrets.npm_token}}
       - run: deno publish --allow-dirty
+        continue-on-error: true
 
 
 

package/README.md

@@ -12,11 +12,26 @@ FunctionalScript is a purely functional programming language and a strict subset
   as a subset of JavaScript.
 - [TypeScript](https://en.wikipedia.org/wiki/TypeScript), as a superset of JavaScript.
 
-[A brief description of FunctionalScript Programming Language](./doc/LANGUAGE.md).
+[A working draft of the FunctionalScript specification](./issues/lang/README.md).
 
 Learn more about
-- [Purely Functional Programming in JavaScript](https://medium.com/@sergeyshandar/purely-functional-programming-in-javascript-91114b1b2dff),
-- [FunctionalScript and I/O](https://medium.com/@sergeyshandar/functionalscript-5cf817345376).
+- [Purely Functional Programming in JavaScript](https://blog.bitsrc.io/purely-functional-programming-in-javascript-91114b1b2dff?sk=5f7132e56902f38fcf4c6164bfa681ed),
+- [FunctionalScript and I/O](https://medium.com/@sergeyshandar/functionalscript-5cf817345376?sk=30b32189a81d1a2dad16c2244f32328d).
+
+FunctionalScript is distributed under [AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html#license-text). Let us know if you need another license by sending an [email](mailto:sergey.oss@proton.me).
+
+## Vision
+
+We aim to create a safe, cross-platform programming language that can work in any JS platform without any build step. There are thousands of programming languages, and we don't want to create another one that others must learn. Instead, we take the opposite approach: we remove everything that makes the most popular and cross-platform language unsafe, insecure, or less portable.
+
+## Applications
+
+FunctionalScript code can be used:
+
+- safely in any JavaScript/TypeScript application or library;
+- as a JSON with expressions, see [DJS](https://medium.com/@sasha.gil/bridging-the-gap-from-json-to-javascript-without-dsls-fee273573f1b);
+- as a query language,
+- as a smart contract programming language in DeFi.
 
 ## Design Principles
 
@@ -27,13 +42,9 @@ In FunctionalScript:
 - A module can depend only on another FunctionalScript module.
 - It also has no standard library. Only a safe subset of standard JavaScript API can be used without referencing other modules.
 
-## Applications
-
-FunctionalScript code can be used:
+## Our Next Step
 
-- in any JavaScript/TypeScript application,
-- as a JSON with expressions,
-- as a query language.
+[Re-architecture of NaNVM](https://medium.com/@sergeyshandar/nanvm-re-architecture-8097f766ec1c?sk=d14ec1daf73ac5442f12ce20b2bc037a).
 
 ## Sponsors
 

package/dev/module.mjs

@@ -1,4 +1,4 @@
-import { readdir, writeFile } from 'node:fs/promises'
+import { readdir, writeFile, readFile } from 'node:fs/promises'
 
 /**
  * @typedef {{
@@ -66,12 +66,12 @@ export const exit = self.Deno ? self.Deno.exit : process.exit
 /** @type {(v: string) => string|undefined} */
 export const env =
     self.Deno ? self.Deno.env.get :
-    a => {
-        const r = Object.getOwnPropertyDescriptor(process.env, a)
-        return r === void 0 ? void 0 :
-            typeof r.get === 'function' ? r.get() :
-            r.value
-    }
+        a => {
+            const r = Object.getOwnPropertyDescriptor(process.env, a)
+            return r === void 0 ? void 0 :
+                typeof r.get === 'function' ? r.get() :
+                    r.value
+        }
 
 export const loadModuleMap = async () => {
     /** @type {() => Promise<UnknownMap>} */
@@ -86,7 +86,7 @@ export const loadModuleMap = async () => {
                     const file = `${p}/${name}`
                     if (i.isDirectory()) {
                         await f(file)
-                    } else if (name.endsWith('.f.cjs') || name.endsWith('.f.mjs')) {
+                    } else if (name.endsWith('.f.cjs') || name.endsWith('.f.mjs') || name.endsWith('.f.js')) {
                         const source = await import(`../${file}`)
                         map.push([file, source.default])
                     }
@@ -178,13 +178,23 @@ const codeAdd = i => p => m => {
     return [result, im]
 }
 
-export const index = async() => {
+export const index = async () => {
+    {
+        const jj = './jsr.json'
+        const jsr_json = JSON.parse(await readFile(jj, { encoding: 'utf8' }))
+        const exports = Object.keys(await loadModuleMap())
+        await writeFile(
+            jj,
+            JSON.stringify({ ...jsr_json, exports }, null, 2))
+    }
+
+    //
     /** @type {FolderMap} */
     let m = {}
     for (const k in await loadModuleMap()) {
         const [, ...s] = k.split('/')
         switch (s[s.length - 1]) {
-            case 'module.f.cjs': case 'module.f.mjs':
+            case 'module.f.cjs': case 'module.f.mjs': case 'module.f.js':
                 m = folderMapAdd(m)(s)
                 break
         }

package/dev/test/module.f.mjs

@@ -46,7 +46,7 @@ import * as Result from '../../types/result/module.f.mjs'
  */
 
 /** @type {(s: string) => boolean} */
-const isTest = s => s.endsWith('test.f.cjs') || s.endsWith('test.f.mjs')
+const isTest = s => s.endsWith('test.f.cjs') || s.endsWith('test.f.mjs') || s.endsWith('test.f.js')
 
 /**
  * @typedef {{

package/dev/test.mjs

@@ -1,4 +1,5 @@
 import { loadModuleMap, exit, env } from './module.mjs'
+import test from './test/module.f.mjs'
 
 /** @type {(f: (s: string) => void) => (s: string) => <T>(_: T) => T} */
 const anyLog = f => s => state => {
@@ -44,15 +45,14 @@ const measure = f => state => {
 const main = async() => {
     const moduleMap = await loadModuleMap()
 
-    /** @type {any} */
-    const f = moduleMap['./dev/test/module.f.mjs'].default
-    const r = f({
+    const r = test({
         moduleMap,
         log: anyLog(console.log),
         error: anyLog(console.error),
         measure,
         tryCatch,
         env,
+        state: void 0,
     })
     exit(r[0])
 }

package/djs/README.md

@@ -9,15 +9,31 @@
 
 ## Next steps
 
-- [ ] rename `fjson` to `djs` (data javascript), File extensions: `.d.cjs`, `.d.mjs`, `.d.js`.
+- [ ] rename `fjson` to `djs` (data javascript), File extensions: `.d.mjs`, `.d.js`.
 - [x] use JS tokenizer 
 - [x] identifiers `{a:5}`
 - [x] big int
-- [ ] `module.exports = ...`
-- [ ] constants `const a = [3];module.exports = { a: a, b: a }`. Serialization `const _0=[3];module.exports={a:_0,b:_0}`
-- [ ] import `const a = require('c.d.cjs');module.exports = { a: a, b: a}`
-- [ ] ES6 import `import a from 'c.d.mjs';export default { a: a, b: a}`
-- [ ] short form `const a = 5;module.exports = { a }`
+- [ ] `export default ...`
+- [ ] constants
+  ```js
+  const a = [3]
+  export default = { a: a, b: a }
+  ```
+  Serialization
+  ```js
+  const _0=[3]
+  export default {a:_0,b:_0}
+  ```
+- [ ] import
+  ```js
+  import a from 'c.d.mjs'
+  export default { a: a, b: a}
+  ```
+- [ ] short form
+  ```js
+  const a = 5;
+  export default { a }
+  ```
 
 Optional, for fun, syntax sugar:
 
@@ -26,5 +42,13 @@ Optional, for fun, syntax sugar:
 
 ## Decidable Language
   
-- [ ] using operator and functions `const a = 2+2+Math.abs(5); module.exports = { a: a };`
-- [ ] decidable functions `const f = a => b => a + b; module.exports = f(1)(2)`?
+- [ ] using operator and functions
+  ```js
+  const a = 2+2+Math.abs(5)
+  export default { a: a }
+  ```
+- [ ] decidable functions?
+  ```js
+  const f = a => b => a + b
+  export default f(1)(2)
+  ```

package/funding.json

@@ -0,0 +1,61 @@
+{
+    "version": "v1.0.0",
+    "entity": {
+        "type": "individual",
+        "role": "owner",
+        "name": "Sergey Shandar",
+        "email": "sergey.oss@proton.me",
+        "description": "Sergey is the main author of FunctionalScript, and other OSS projects related to content-addressable infrastructure",
+        "webpageUrl": {
+            "url": "https://github.com/functionalscript/functionalscript"
+        }
+    },
+    "projects": [
+        {
+            "guid": "functionalscript",
+            "name": "FunctionalScript",
+            "description": "FunctionalScript is a purely functional safe subset of JavaScript",
+            "webpageUrl": {
+                "url": "https://github.com/functionalscript/functionalscript"
+            },
+            "repositoryUrl": {
+                "url": "https://github.com/functionalscript/functionalscript"
+            },
+            "licenses": [
+                "spdx:AGPL-3.0-only"
+            ],
+            "tags": [
+                "programming",
+                "web-development",
+                "software-engineering",
+                "developer-tools",
+                "programming-language",
+                "cryptography",
+                "smart-contract"
+            ]
+        }
+    ],
+    "funding": {
+        "channels": [
+            {
+                "guid": "github",
+                "type": "other",
+                "address": "https://github.com/sponsors/sergey-shandar"
+            }
+        ],
+        "plans": [
+            {
+                "guid": "nanvm",
+                "status": "active",
+                "name": "NaNVM",
+                "description": "NaNVM is a virtual machine for the FunctionalScript",
+                "amount": 0,
+                "currency": "USD",
+                "frequency": "one-time",
+                "channels": [
+                    "github"
+                ]
+            }
+        ]
+    }
+}

package/issues/README.md

@@ -1,20 +1,24 @@
 # Issues
 
 1. [X] [test-debug](./test-debug.md).
-2. [ ] [esm](./esm.md)
-3. [ ] [publish](publish.md)
-4. [ ] fix index generation by including sub modules `{ ...m, add: mAdd, remove: mRemove}`.
-5. [ ] Conventions:
+2. [X] [esm](./esm.md)
+3. [ ] [djs](./djs.md)
+4. [ ] VM Rust project
+5. [ ] [publish](publish.md)
+6. [ ] fix index generation by including sub modules `{ ...m, add: mAdd, remove: mRemove}`.
+7. [ ] Conventions:
     ```js
     import list, * as List from 'list.mjs'
     // list is for objects.
     // List is for types and should be ignored by FJS or errored if used in code.
     ```
-6. [ ] PoC: Replace `while` with recursive generators
-7. Two sets of property filters:
+8. Move logic from `.mjs` files to `.f.mjs` files.
+9. Two sets of property filters:
    - usage `.b`:
      - `constructor`
      - ...
    - call `.b()`:
      - `push`
      - ...
+10. [ ] Replace file extensions from `.mjs` to `.js`. Make sure `package.json/type` is equal to `module`. May be later: https://v8.dev/features/modules#mjs
+11. [ ] [fs-load](./fs-load.md)

package/issues/djs.md

@@ -0,0 +1,57 @@
+# DJS
+
+Parse this code
+
+```js
+import a from 'c.d.mjs'
+const c = [12, 'x']
+export default { a: a, b: a, c: c}
+```
+
+Into this structure:
+
+```ts
+type Module = {
+  modules: string[]
+  func: Func
+}
+
+// the last constant from the array is a return
+type Func = Const[]
+
+type Const = Primitive | CObject | CArray |CRef | ARef 
+
+type Primitive = number|string|boolean|null|bigint
+
+type CRef = ['cref', number]
+
+type ARef = ['aref', number]
+
+type CObject = ['object', {
+  [k in string]: Const
+}]
+
+type CArray = ['array', [Const]]
+```
+
+Where `func` is a description of the function:
+
+```js
+(...args) => {
+  const const0 = [12, 'x']
+  return { a: args[0], b: args[0], c: const0}
+}
+```
+
+## Parsed Example
+
+```js
+export default
+// array of constants
+[
+  // const const0
+  ['array', [12, 'x']],
+  // return
+  ['object', { 'a': ['aref', 0], 'b': ['aref', 0], c: ['cref', 0] }]
+]
+```

package/issues/fs-load.md

@@ -0,0 +1,13 @@
+# FS VM load/save
+
+sketch / mention future documentation on errors / exceptions and execution scheme in general, for example:
+
+The host environment has well defined operations like 'Load' (takes a "root" module path, optional extra parameters), 'Execute' (takes the successful result of 'Load', optional extra parameters), 'Save' (takes the successful result of 'Load', optional extra parameters).
+
+'Load' time errors are communicated to the host environment (e.g. to output error diagnostics on the console). In presence of load time errors there is no successful result of 'Load', so there is nothing to pass to Execute, Save. However, it makes sense to have results of a partially successful 'Load' even though they cannot be used in 'Execute', 'Save' - for example, in language server protocol scenarios.
+
+'Save' corresponds to code / data transformations other than 'Execute', e.g. bundling. 'Save' time errors are communicated to the host environment. It might make sense to have results of a partially successful 'Save' (similarly to abovementioned scenarios for partially successful 'Load' results).
+
+'Execute' corresponds to calling the function that is the default export of the "root" module and that takes produces side effects on the environment. Execution ends with a halt caused either by the inner logic of the code (e.g. the root function successfully completes, or an unhandled error happens), or by external causes (e.g. the user stops the execution).
+
+Now, does a proper FS system provide user code means to handle errors, e.g. an exception handling mechanism similar to JS's exception handling?

package/issues/lang/1000-json.md

@@ -0,0 +1,12 @@
+# JSON
+
+JSON forms a tree of values.
+
+```json
+{
+    "a": null,
+    "b": [-42.5, false, "hello"]
+}
+```
+
+File extension: `.json`.

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

@@ -0,0 +1,11 @@
+# Default Export
+
+Parse `export default` and then JSON. This's enough to have the same functionality as JSON.
+
+```js
+export default 5
+```
+
+Depends on [JSON](./1110-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

@@ -0,0 +1,14 @@
+# 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

@@ -0,0 +1,10 @@
+# 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

@@ -0,0 +1,12 @@
+# 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

@@ -0,0 +1,25 @@
+# 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

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

package/issues/lang/2320-bigint.md

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

package/issues/lang/2330-grouping.md

@@ -0,0 +1,11 @@
+# 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/2340-operators.md

@@ -0,0 +1,41 @@
+# 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/2351-property-accessor.md

@@ -0,0 +1,44 @@
+# Property Accessor
+
+- `.`
+- `?.`
+
+FunctionalScript is a strict subset of JavaScript and should behave the same way as JavaScript or reject JS code during compilation as non-valid FS code. However, every object in JavaScript has inherited properties, such as [`constructor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor) and [`__proto__`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/proto). These properties can cause side effects. For example:
+
+```js
+const f = (() => {}).constructor
+const g = f(`console.log('hello')`)
+g() // we received direct access to I/O
+```
+
+According to FunctionScript principles, an FS compiler should reject such code during compilation. So, the compiler will prohibit the use of `construct` and `__proto__` after `.` and `?.`.
+
+If an object has its own properties with such names (e.g. `constructor`) then we can access it using the [Object.getOwnPropertyDescriptor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor) function instead. The function doesn't return inherited properties.
+
+```js
+const f = (() => {}).constructor
+const g = Object.getOwnPropertyDescriptor(f, 'constructor') // g === undefined
+
+const myObject = { constructor: 42 }
+const c = Object.getOwnPropertyDescriptor(myObject, 'constructor').value // c === 42
+```
+
+Here's the reason why we prohibit `__proto__`:
+
+```js
+const p = (() => {}).__proto__
+const f = Object.getOwnPropertyDescriptor(p, 'constructor').value
+const g = f(`console.log('hello')`)
+g() // side-effect
+```
+
+## Example
+
+```js
+const a = { x: 3}
+export default a.x
+```
+
+Depends on [const](./2120-const.md), [default-import](./2130-default-import.md) and [undefined](./2310-undefined.md).
+
+See <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors>.

package/issues/lang/2352-property-call.md

@@ -0,0 +1,43 @@
+# Function Call With Property Accessor
+
+Operators `a.b()`, `a?.b()`.
+
+```js
+const x = a.b(5)
+```
+
+For `null?.b(x())`. We follow the same behavior as JS, so the `x` function will not be called.
+
+Not allowed (additional to `constructor` and `__proto__`, see [property-accessor](./2351-property-accessor.md)):
+
+- `__defineGetter__`
+- `__defineSetter__`
+- `__lookupGetter__`
+- `__lookupSetter__`
+- `isPrototypeOf` FS has no prototype concept because it has no inheritance.
+- `toLocaleString` because it depends on the locale, which is a side-effect.
+
+Also, from a function:
+
+- `apply`
+- `bind`
+- `call`
+
+Also, from an array:
+
+- `copyWithin`
+- `entries` - returns an iterator.
+- `values` - returns an iterator.
+- `keys` - returns an iterator.
+- `pop`
+- `push`
+- `shift`
+- `unshift`
+- `sort`
+- `reverse`
+
+FunctionalScript doesn't allow direct access to iterators. An iterator can be mutated by `.next()` or `for()`. Indirect access to iterators is allowed through the `Iterable` interface. For example 
+```js
+for (const i of [1, 2]) { }
+```
+In this example, the loop gets a temporary iterator from the iterable interface of `[1, 2]` then use it and discard it. A user can't have direct access to the iterator and can't make a copy of it. 

package/issues/lang/2353-property-at.md

@@ -0,0 +1,19 @@
+# At
+
+`a[42]`, `a['str']`, `a[+i]`.
+
+```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 `a[i]`, `i` has to be a `number` or known `string`, which is not equal to prohibited words, see [property-accessor](./2351-property-accessor.md). If we don't know what is `i`, `+` requires before `i`.
+
+It means that 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. In the future, FS may try deeper analyses and type inference can help a lot.
+
+Depends on [property-accessor](./2351-property-accessor.md).