porffor 0.25.1 → 0.25.3

package/CONTRIBUTING.md

@@ -23,7 +23,6 @@ The repo comes with easy alias scripts for Unix and Windows, which you can use l
 
 You can also swap out `node` in the alias to use another runtime like Deno (`deno run -A ...`) or Bun (`bun ...`), or just use it yourself (eg `node runner/index.js ...`, `bun runner/index.js ...`). Node, Deno, Bun should work.
 
-
 ### Precompile
 
 **If you update any file inside `compiler/builtins` you will need to do this for it to update inside Porffor otherwise your changes will have no effect.** Run `./porf precompile` to precompile. It may error during this, if so, you might have an error in your code or there could be a compiler error with Porffor (feel free to ask for help as soon as you encounter any errors with it).
@@ -98,7 +97,7 @@ Loads the character code at the pointer `pointer` **for a String**.[^1]
 Porffor.wasm.i32.store(pointer, length, 0, 0)
 ```
 
-Stores the length `length` at pointer `pointer`, setting the length of an object. This is mostly unneeded today as you can just do `obj.length = length`. (The `0, 4` args are necessary for the Wasm instruction, but you don't need to worry about them (`0` alignment, `0` byte offset).
+Stores the length `length` at pointer `pointer`, setting the length of an object. This is mostly unneeded today as you can just do `obj.length = length`. [^1]
 
 <br>
 
@@ -200,13 +199,147 @@ Store the character code into the `out` pointer variable, and increment it.
 
 - For declaring variables, you must use explicit type annotations currently (eg `let a: number = 1`, not `let a = 1`).
 - You might spot `Porffor.fastOr`/`Porffor.fastAnd`, these are non-short circuiting versions of `||`/`&&`, taking any number of conditions as arguments. You shouldn't don't need to use or worry about these.
-- **There are ~no objects, you cannot use them.**
-- Attempt to avoid string/array-heavy code and use more variables instead if possible, easier on memory and CPU/perf.
+- Attempt to avoid object/string/array-heavy code and use more variables instead if possible, easier on memory and CPU/perf.
 - Do not set a return type for prototype methods, it can cause errors/unexpected results.
 - You cannot use other functions in the file not exported, or variables not inside the current function.
 - `if (...)` uses a fast truthy implementation which is not spec-compliant as most conditions should be strictly checked. To use spec-compliant behavior, use `if (Boolean(...))`.
 - For object (string/array/etc) literals, you must use a variable eg `const out: bytestring = 'foobar'; console.log(out);` instead of `console.log('foobar')` due to precompile's allocator constraints.
-- Generally prefer/use non-strict equality ops (`==`/`!=`).
+- You should generally use non-strict equality ops (`==`/`!=`).
+
+<br>
+
+### Porffor.wasm
+This is a macro that is essentially equivalent to C's `asm` macro. It allows you to write inline Wasm bytecode in a similar format to [WAT](https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format).
+
+Let's look at an example to better illustrate how the format works.
+
+```ts
+export const add_i32 = (a: any, b: any) => {
+  Porffor.wasm`
+  local aCasted i32
+  local bCasted i32
+  returns i32 i32
+
+  ;; if both types are number
+  local.get ${a+1}
+  i32.const 1
+  i32.eq
+  local.get ${b+1}
+  i32.const 1
+  i32.eq
+  i32.and
+  if
+    local.get ${a}
+    i32.from
+    local.set aCasted
+
+    local.get ${b}
+    i32.from
+    local.set bCasted
+
+    local.get aCasted
+    local.get bCasted
+    i32.add
+    i32.const 1
+    return
+  end
+
+  ;; return (0, 0) otherwise
+  i32.const 0
+  i32.const 0
+  return`;
+}
+```
+
+---
+
+```
+local aCasted i32
+local bCasted i32
+```
+
+Here we define two locals, which you can think of as typed variables. Here both of them have the type of `i32`, which was explained above. This type can also be `f64` or `i64`, which are doubles and 64-bit integers respectively.
+
+---
+
+```
+returns i32 i32
+```
+
+This sets the return type of the function, what the stack must look like before a `return` instruction. Normally Porffor functions have the return type `(f64, i32)`, which represents the valtype (usually f64) and an i32 type.
+
+> [!WARNING]
+> This is something you have to be incredibly careful with, as Porffor expects most functions to return `(valtype, i32)`. Be incredibly careful when using this.
+
+---
+
+```
+;; if both types are number
+```
+
+This is a comment. `;;` is Wasm's `//`.
+
+---
+
+```
+local.get ${a+1}
+i32.const 1
+i32.eq
+local.get ${b+1}
+i32.const 1
+i32.eq
+i32.and
+```
+
+This part is a little more complicated, first you have to understand how Wasm represents function parameters and local variables in general. When looking at the decompiled output of something like `let a = 1;`, you'll likely see something like this:
+```
+f64.const 1
+i32.const 1
+local.set 1 ;; a#type (i32)
+local.set 0 ;; a
+```
+Here the `i32.const 1` is equivalent to `TYPES.number`, which aligns with what we told Porffor to do, but what's up with the `local.set`s to a number? Well, internally locals are represented with indexes, and in this example `a` was assigned 0, and `a#type` was assigned 1.
+
+That's where `local.get ${a+1}` comes from, it's Porffor's way of saying "get the local variable at index of `a` plus one". In most cases, this is the variable's type. The rest of the snippet is just checking if both of the parameters' types are equal to `TYPES.number`.
+
+---
+
+```
+if
+  local.get ${a}
+  i32.from
+  local.set aCasted
+
+  local.get ${b}
+  i32.from
+  local.set bCasted
+```
+
+Here we start an if block, equivalent to JS's `if (...) {}`, and as the locals' names imply, cast them to `i32`s. There is one strange thing about this section though, if you look at Wasm's list of instructions you won't find a `i32.from`. This is because Porffor has custom instructions for converting to and from the valtype. In this case, converting the valtype into an `i32`. There are a few more of these instructions, but in general these instructions come in the format of `type.from` (create `type` from valtype) and `type.to` (create valtype from `type`). You can find a full list at the bottom of `codegen.js`.
+
+---
+
+```
+  local.get aCasted
+  local.get bCasted
+  i32.add
+  i32.const 1
+  return
+end
+```
+
+Here, we get our two casted locals and add them together, returning the result and a `i32` with the value of 1. We then end the if block with the `end` instruction.
+
+---
+
+```
+;; return (0, 0) otherwise
+i32.const 0
+i32.const 0
+return
+```
+
+Finally, we return `(0, 0)` if either type is not a number. This example was very contrived, but should give you a good sense of how to use `Porffor.wasm`.
 
 <br>
 
@@ -259,4 +392,9 @@ It will also log new passes/fails. Be careful as sometimes the overall passes ca
 
 <br>
 
-[^1]: The `0, 4` args are necessary for the Wasm instruction, but you don't need to worry about them (`0` alignment, `4` byte offset for length).
+### Resources
+
+- [MDN](https://developer.mozilla.org/en-US/), not only a great resource for learning JS, but also for implementing it, as it has high level descriptions of functionality, as well as links to the relevant portions of the spec that govern the feature.
+- [WebAssembly Opcodes](https://pengowray.github.io/wasm-ops/), this website not only describes what each wasm instruction does but the necessary stack needed, and contains some other useful resources as well.
+
+[^1]: The last two args are necessary for the Wasm instruction, but you don't need to worry about them (the first is alignment, the second is byte offset).

package/README.md

@@ -68,8 +68,8 @@ Expect nothing to work! Only very limited JS is currently supported. See files i
 - `-O3` to enable advanceder opt (precompute const math). unstable!
 
 ## Limitations
-- No full object support yet
 - Little built-ins/prototype
+- No object prototypes yet
 - No async/promise/await
 - No variables between scopes (except args and globals)
 - No `eval()` etc (since it is AOT)
@@ -103,7 +103,7 @@ These include some early (stage 1/0) and/or dead (last commit years ago) proposa
 - Declaring functions
 - Calling functions
 - `return`
-- `let`/`const`/`var` basic declarations
+- Basic declarations (`let`/`const`/`var`)
 - Some basic integer operators (`+-/*%`)
 - Some basic integer bitwise operators (`&|`)
 - Equality operators (`==`, `!=`, etc)
@@ -111,18 +111,18 @@ These include some early (stage 1/0) and/or dead (last commit years ago) proposa
 - Some unary operators (`!`, `+`, `-`)
 - Logical operators (`&&`, `||`)
 - Declaring multiple variables in one (`let a, b = 0`)
+- Array destructuring (`let [a, ...b] = foo`)
 - Global variables (`var`/none in top scope)
-- Functions returning 1 number
-- Bool literals as ints (not real type)
+- Booleans
 - `if` and `if ... else`
 - Anonymous functions
 - Setting functions using vars (`const foo = function() { ... }`)
 - Arrow functions
-- `undefined`/`null` as ints (hack)
+- `undefined`/`null`
 - Update expressions (`a++`, `++b`, `c--`, etc)
 - `for` loops (`for (let i = 0; i < N; i++)`, etc)
-- *Basic* objects (hack)
-- `console.log` (hack)
+- Basic objects (no prototypes)
+- `console.log`
 - `while` loops
 - `break` and `continue`
 - Named export funcs
@@ -131,7 +131,7 @@ These include some early (stage 1/0) and/or dead (last commit years ago) proposa
 - Conditional/ternary operator (`cond ? a : b`)
 - Recursive functions
 - Bare returns (`return`)
-- `throw` (literals only)
+- `throw` (literals only, hack for `new Error`)
 - Basic `try { ... } catch { ... }` (no error given)
 - Calling functions with non-matching arguments (eg `f(a, b); f(0); f(1, 2, 3);`)
 - `typeof`
@@ -145,11 +145,15 @@ These include some early (stage 1/0) and/or dead (last commit years ago) proposa
 - String comparison (eg `'a' == 'a'`, `'a' != 'b'`)
 - Nullish coalescing operator (`??`)
 - `for...of` (arrays and strings)
+- `for...in`
 - Array member setting (`arr[0] = 2`, `arr[0] += 2`, etc)
 - Array constructor (`Array(5)`, `new Array(1, 2, 3)`)
 - Labelled statements (`foo: while (...)`)
 - `do...while` loops
 - Optional parameters (`(foo = 'bar') => { ... }`)
+- Rest parameters (`(...foo) => { ... }`)
+- `this`
+- Constructors (`new Foo`)
 
 ### Built-ins
 
@@ -223,16 +227,27 @@ Porffor can run Test262 via some hacks/transforms which remove unsupported featu
 
 ## Codebase
 - `compiler`: contains the compiler itself
-  - `builtins.js`: all built-ins of the engine (spec, custom. vars, funcs)
+  - `2c.js`: porffor's custom wasm-to-c engine
+  - `allocators.js`: static and dynamic allocators to power various language features
+  - `assemble.js`: assembles wasm ops and metadata into a wasm module/file
+  - `builtins.js`: all manually written built-ins of the engine (spec, custom. vars, funcs)
+  - `builtins_object.js`: all the various built-in objects (think `String`, `globalThis`, etc.)
+  - `builtins_precompiled.js`: dynamically generated builtins from the `builtins/` folder
   - `codegen.js`: code (wasm) generation, ast -> wasm. The bulk of the effort
+  - `cyclone.js`: wasm partial constant evaluator (it is fast and dangerous hence "cyclone")
   - `decompile.js`: basic wasm decompiler for debug info
   - `embedding.js`: utils for embedding consts
   - `encoding.js`: utils for encoding things as bytes as wasm expects
   - `expression.js`: mapping most operators to an opcode (advanced are as built-ins eg `f64_%`)
+  - `havoc.js`: wasm rewrite library (it wreaks havoc upon wasm bytecode hence "havoc")
   - `index.js`: doing all the compiler steps, takes code in, wasm out
   - `opt.js`: self-made wasm bytecode optimizer
   - `parse.js`: parser simply wrapping acorn
-  - `assemble.js`: assembles wasm ops and metadata into a wasm module/file
+  - `pgo.js`: a profile guided optimizer
+  - `precompile.js`: the tool to generate `builtins_precompied.js`
+  - `prefs.js`: a utility to read command line arguments
+  - `prototype.js`: some builtin prototype functions
+  - `types.js`: definitions for each of the builtin types
   - `wasmSpec.js`: "enums"/info from wasm spec
   - `wrap.js`: wrapper for compiler which instantiates and produces nice exports
 
@@ -249,16 +264,16 @@ Porffor can run Test262 via some hacks/transforms which remove unsupported featu
 - `test262`: test262 runner and utils
 
 ## Usecases
-Basically none right now (other than giving people headaches). Potential ideas:
+Currently, Porffor is seriously limited in features and functionality, however it has some key benefits:
 - Safety. As Porffor is written in JS, a memory-safe language\*, and compiles JS to Wasm, a fully sandboxed environment\*, it is quite safe. (\* These rely on the underlying implementations being secure. You could also run Wasm, or even Porffor itself, with an interpreter instead of a JIT for bonus security points too.)
 - Compiling JS to native binaries. This is still very early!
+- Inline Wasm for when you want to beat the compiler in performance, or just want fine grained functionality.
+- Potential for SIMD operations and other lower level concepts.
 - More in future probably?
 
 ## Todo
 No particular order and no guarentees, just what could happen soon™
 
-- Objects
-  - Basic object expressions (eg `{}`, `{ a: 0 }`)
 - Asur
   - Support memory
   - Support exceptions
@@ -272,8 +287,6 @@ No particular order and no guarentees, just what could happen soon™
 - Runtime
   - WASI target
   - Run precompiled Wasm file if given
-- Docs
-  - Update codebase readme section
 - Cool proposals
   - [Optional Chaining Assignment](https://github.com/tc39/proposal-optional-chaining-assignment)
   - [Modulus and Additional Integer Math](https://github.com/tc39/proposal-integer-and-modulus-math)
@@ -303,7 +316,6 @@ Porffor intentionally does not use Wasm proposals which are not commonly impleme
 - Exception handling (optional, only for errors)
 - Tail calls (opt-in, off by default)
 
-
 ## FAQ
 
 ### 1. Why the name?

package/compiler/builtins.js

@@ -190,7 +190,7 @@ export const BuiltinFuncs = function() {
       ...number(TYPES.number, Valtype.i32),
       [ Opcodes.local_get, 1 ],
       ...number(TYPES.number, Valtype.i32),
-      [ Opcodes.call, builtin('__Math_pow') ],
+      [ Opcodes.call, ...builtin('__Math_pow') ],
       [ Opcodes.drop ],
     ]
   };

package/compiler/builtins_objects.js

@@ -1,4 +1,4 @@
-import { Opcodes, PageSize, Valtype } from './wasmSpec.js';
+import { Blocktype, Opcodes, PageSize, Valtype } from './wasmSpec.js';
 import { TYPES } from './types.js';
 import { number } from './embedding.js';
 
@@ -6,64 +6,92 @@ export default function({ builtinFuncs }, Prefs) {
   const done = new Set();
   const object = (name, props) => {
     done.add(name);
+    const prefix = name === 'globalThis' ? '' : `__${name}_`;
+
+    builtinFuncs['#get_' + name] = {
+      params: [],
+      locals: [],
+      globals: [ Valtype.i32 ],
+      globalNames: [ '#getptr_' + name ],
+      returns: [ Valtype.i32 ],
+      returnType: TYPES.object,
+      wasm: (scope, { allocPage, makeString, generate, getNodeType, builtin }) => {
+        if (globalThis.precompile) return [ [ 'get object', name ] ];
+
+        // todo/perf: precompute bytes here instead of calling real funcs if we really care about perf later
+
+        const page = allocPage(scope, `builtin object: ${name}`);
+        const ptr = page === 0 ? 4 : page * PageSize;
+
+        const out = [
+          // check if already made/cached
+          [ Opcodes.global_get, 0 ],
+          [ Opcodes.if, Blocktype.void ],
+            [ Opcodes.global_get, 0 ],
+            [ Opcodes.return ],
+          [ Opcodes.end ],
+
+          // set cache & ptr for use
+          ...number(ptr, Valtype.i32),
+          [ Opcodes.global_set, 0 ],
+        ];
 
-    let cached;
-    this[name] = (scope, { allocPage, makeString, generateIdent, getNodeType, builtin }) => {
-      if (cached) {
-        return number(cached);
-      }
-
-      // todo: precompute bytes here instead of calling real funcs if we really care about perf later
+        for (const x in props) {
+          let value = {
+            type: 'Identifier',
+            name: prefix + x
+          };
 
-      const page = allocPage(scope, `builtin object: ${name}`);
-      const ptr = page === 0 ? 4 : page * PageSize;
-      cached = ptr;
+          let flags = 0b0000;
 
-      const out = [];
+          const d = props[x];
+          if (d.configurable) flags |= 0b0010;
+          if (d.enumerable) flags |= 0b0100;
+          if (d.writable) flags |= 0b1000;
 
-      for (const x in props) {
-        const value = {
-          type: 'Identifier',
-          name: '__' + name + '_' + x
-        };
+          // hack: do not generate objects inside of objects as it causes issues atm
+          if (this[prefix + x]?.type === TYPES.object) value = { type: 'ObjectExpression', properties: [] };
 
-        let flags = 0b0000;
+          out.push(
+            [ Opcodes.global_get, 0 ],
+            ...number(TYPES.object, Valtype.i32),
 
-        const d = props[x];
-        if (d.configurable) flags |= 0b0010;
-        if (d.enumerable) flags |= 0b0100;
-        if (d.writable) flags |= 0b1000;
-
-        out.push(
-          ...number(ptr, Valtype.i32),
-          ...number(TYPES.object, Valtype.i32),
+            ...makeString(scope, x, false, `#builtin_object_${name}_${x}`),
+            Opcodes.i32_to_u,
+            ...number(TYPES.bytestring, Valtype.i32),
 
-          ...makeString(scope, x, false, `#builtin_object_${name}_${x}`),
-          Opcodes.i32_to_u,
-          ...number(TYPES.bytestring, Valtype.i32),
+            ...generate(scope, value),
+            ...getNodeType(scope, value),
 
-          ...generateIdent(scope, value),
-          ...getNodeType(scope, value),
+            ...number(flags, Valtype.i32),
+            ...number(TYPES.number, Valtype.i32),
 
-          ...number(flags, Valtype.i32),
-          ...number(TYPES.number, Valtype.i32),
+            [ Opcodes.call, ...builtin('__Porffor_object_define') ],
+            [ Opcodes.drop ],
+            [ Opcodes.drop ]
+          );
+        }
 
-          [ Opcodes.call, ...builtin('__Porffor_object_define') ],
-          [ Opcodes.drop ],
-          [ Opcodes.drop ]
+        out.push(
+          // return ptr
+          [ Opcodes.global_get, 0 ]
         );
+        return out;
       }
-
-      out.push(...number(ptr));
-      return out;
     };
+
+
+    this[name] = (scope, { builtin }) => [
+      [ Opcodes.call, ...builtin('#get_' + name) ],
+      Opcodes.i32_from_u
+    ];
     this[name].type = TYPES.object;
 
     for (const x in props) {
       const d = props[x];
 
       if (d.value) {
-        const k = '__' + name + '_' + x;
+        const k = prefix + x;
 
         if (typeof d.value === 'number') {
           this[k] = number(d.value);
@@ -189,7 +217,42 @@ export default function({ builtinFuncs }, Prefs) {
     });
   }
 
-  object('globalThis', {})
+  const enumerableGlobals = [ 'atob', 'btoa', 'performance', 'crypto', 'navigator' ];
+  object('globalThis', {
+    // 19.1 Value Properties of the Global Object
+    // https://tc39.es/ecma262/#sec-value-properties-of-the-global-object
+    // 19.1.1 globalThis
+    globalThis: {
+      writable: true,
+      enumerable: false,
+      configurable: true
+    },
+
+    // 19.1.2 Infinity
+    // 19.1.3 NaN
+    // 19.1.4 undefined
+    ...props({
+      writable: false,
+      enumerable: false,
+      configurable: false
+    }, [ 'Infinity', 'NaN', 'undefined' ]),
+
+    // 19.2 Function Properties of the Global Object
+    // https://tc39.es/ecma262/#sec-function-properties-of-the-global-object
+    // 19.3 Constructor Properties of the Global Object
+    // https://tc39.es/ecma262/#sec-constructor-properties-of-the-global-object
+    ...props({
+      writable: true,
+      enumerable: false,
+      configurable: true
+    }, builtinFuncKeys.filter(x => !x.startsWith('__') && !enumerableGlobals.includes(x) && !x.startsWith('f64') && !x.startsWith('i32'))),
+
+    ...props({
+      writable: true,
+      enumerable: true,
+      configurable: true
+    }, enumerableGlobals)
+  });
 
   if (Prefs.logMissingObjects) for (const x of Object.keys(builtinFuncs).concat(Object.keys(this))) {
     if (!x.startsWith('__')) continue;