porffor 0.25.2 → 0.25.4

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>
 
@@ -209,6 +208,141 @@ Store the character code into the `out` pointer variable, and increment it.
 
 <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>
+
 ## Formatting/linting
 
 There is 0 setup for this (right now). You can try looking through the other built-ins files but do not worry about it a lot, I honestly do not mind going through and cleaning up after a PR as long as the code itself is good :^)
@@ -258,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/promise.ts

@@ -0,0 +1,247 @@
+import type {} from './porffor.d.ts';
+
+export const __ecma262_NewPromiseReactionJob = (reaction: any[], argument: any): any[] => {
+  const job: any[] = Porffor.allocateBytes(22); // 2 length
+  job[0] = reaction;
+  job[1] = argument;
+
+  return job;
+};
+
+const jobQueue: any[] = new Array(0);
+export const __ecma262_HostEnqueuePromiseJob = (job: any[]): void => {
+  Porffor.fastPush(jobQueue, job);
+};
+
+// 27.2.1.8 TriggerPromiseReactions (reactions, argument)
+// https://tc39.es/ecma262/#sec-triggerpromisereactions
+export const __ecma262_TriggerPromiseReactions = (reactions: any[], argument: any): void => {
+  // 1. For each element reaction of reactions, do
+  for (const reaction of reactions) {
+    // a. Let job be NewPromiseReactionJob(reaction, argument).
+    // b. Perform HostEnqueuePromiseJob(job.[[Job]], job.[[Realm]]).
+    __ecma262_HostEnqueuePromiseJob(__ecma262_NewPromiseReactionJob(reaction, argument));
+  }
+
+  // 2. Return unused.
+};
+
+
+// 27.2.1.6 IsPromise (x)
+// https://tc39.es/ecma262/#sec-ispromise
+export const __ecma262_IsPromise = (x: any): boolean => {
+  // custom impl
+  return Porffor.rawType(x) == Porffor.TYPES.promise;
+};
+
+// 27.2.1.4 FulfillPromise (promise, value)
+// https://tc39.es/ecma262/#sec-fulfillpromise
+export const __ecma262_FulfillPromise = (promise: any[], value: any): void => {
+  // 1. Assert: The value of promise.[[PromiseState]] is pending.
+  // todo
+
+  // 2. Let reactions be promise.[[PromiseFulfillReactions]].
+  const reactions: any[] = promise[2]; // fulfillReactions
+
+  // 3. Set promise.[[PromiseResult]] to value.
+  promise[0] = value;
+
+  // 4. Set promise.[[PromiseFulfillReactions]] to undefined.
+  promise[2] = undefined;
+
+  // 5. Set promise.[[PromiseRejectReactions]] to undefined.
+  promise[3] = undefined;
+
+  // 6. Set promise.[[PromiseState]] to fulfilled.
+  promise[1] = 1;
+
+  // 7. Perform TriggerPromiseReactions(reactions, value).
+  __ecma262_TriggerPromiseReactions(reactions, value);
+
+  // 8. Return unused.
+};
+
+// 27.2.1.7 RejectPromise (promise, reason)
+// https://tc39.es/ecma262/#sec-rejectpromise
+export const __ecma262_RejectPromise = (promise: any[], reason: any): void => {
+  // 1. Assert: The value of promise.[[PromiseState]] is pending.
+  // todo
+
+  // 2. Let reactions be promise.[[PromiseRejectReactions]].
+  const reactions: any[] = promise[3]; // rejectReactions
+
+  // 3. Set promise.[[PromiseResult]] to reason.
+  promise[0] = reason;
+
+  // 4. Set promise.[[PromiseFulfillReactions]] to undefined.
+  promise[2] = undefined;
+
+  // 5. Set promise.[[PromiseRejectReactions]] to undefined.
+  promise[3] = undefined;
+
+  // 6. Set promise.[[PromiseState]] to rejected.
+  promise[1] = 2;
+
+  // 7. If promise.[[PromiseIsHandled]] is false, perform HostPromiseRejectionTracker(promise, "reject").
+  // unimplemented
+
+  // 8. Perform TriggerPromiseReactions(reactions, reason).
+  __ecma262_TriggerPromiseReactions(reactions, reason);
+
+  // 9. Return unused.
+};
+
+
+export const __Porffor_promise_noop = () => {};
+
+let activePromise: any;
+export const __Porffor_promise_resolve = (value: any): any => {
+  // todo: if value is own promise, reject with typeerror
+
+  if (__ecma262_IsPromise(value)) {
+    printStatic('todo res');
+    // todo
+  } else {
+    __ecma262_FulfillPromise(activePromise, value);
+  }
+
+  return undefined;
+};
+
+export const __Porffor_promise_reject = (reason: any): any => {
+  if (__ecma262_IsPromise(reason)) {
+    printStatic('todo rej');
+    // todo
+  } else {
+    __ecma262_RejectPromise(activePromise, reason);
+  }
+
+  return undefined;
+};
+
+export const __Porffor_promise_create = (): any[] => {
+  // Promise [ result, state, fulfillReactions, rejectReactions ]
+  const obj: any[] = Porffor.allocateBytes(40); // 4 length
+
+  // result = undefined
+  obj[0] = undefined;
+
+  // enum PromiseState { pending = 0, fulfilled = 1, rejected = 2 }
+  // state = .pending
+  obj[1] = 0;
+
+  // fulfillReactions = []
+  const fulfillReactions: any[] = Porffor.allocateBytes(256); // max length: 28
+  obj[2] = fulfillReactions;
+
+  // rejectReactions = []
+  const rejectReactions: any[] = Porffor.allocateBytes(256); // max length: 28
+  obj[3] = rejectReactions;
+
+  return obj;
+};
+
+export const __Porffor_promise_runJobs = () => {
+  while (true) {
+    let x: any = jobQueue.shift();
+    if (x == null) break;
+
+    const reaction: any[] = x[0];
+    const handler: Function = reaction[0];
+    const outPromise: any[] = reaction[1];
+
+    const value: any = x[1];
+
+    // todo: handle thrown errors in handler?
+    const outValue: any = handler(value);
+
+    // todo: should this be resolve or fulfill?
+    __ecma262_FulfillPromise(outPromise, outValue);
+  }
+};
+
+
+export const Promise = function (executor: any): Promise {
+  if (!new.target) throw new TypeError("Constructor Promise requires 'new'");
+  if (Porffor.rawType(executor) != Porffor.TYPES.function) throw new TypeError('Promise executor is not a function');
+
+  const obj: any[] = __Porffor_promise_create();
+
+  activePromise = obj;
+  executor(__Porffor_promise_resolve, __Porffor_promise_reject);
+
+  const pro: Promise = obj;
+  return pro;
+};
+
+
+export const __Promise_prototype_then = (_this: any, onFulfilled: any, onRejected: any) => {
+  // 27.2.5.4 Promise.prototype.then (onFulfilled, onRejected)
+  // https://tc39.es/ecma262/#sec-promise.prototype.then
+
+  // 1. Let promise be the this value.
+  // 2. If IsPromise(promise) is false, throw a TypeError exception.
+  if (!__ecma262_IsPromise(_this)) throw new TypeError('Promise.prototype.then called on non-Promise');
+
+  // 27.2.5.4.1 PerformPromiseThen (promise, onFulfilled, onRejected [, resultCapability])
+  // https://tc39.es/ecma262/#sec-performpromisethen
+
+  if (Porffor.rawType(onFulfilled) != Porffor.TYPES.function) onFulfilled = __Porffor_promise_noop;
+  if (Porffor.rawType(onRejected) != Porffor.TYPES.function) onRejected = __Porffor_promise_noop;
+
+  const promise: any[] = _this;
+  const state: i32 = promise[1];
+
+  const outPromise: any[] = __Porffor_promise_create();
+
+  const fulfillReaction: any[] = Porffor.allocateBytes(22); // 2 length
+  fulfillReaction[0] = onFulfilled;
+  fulfillReaction[1] = outPromise;
+
+  const rejectReaction: any[] = Porffor.allocateBytes(22); // 2 length
+  rejectReaction[0] = onRejected;
+  rejectReaction[1] = outPromise;
+
+  // 9. If promise.[[PromiseState]] is pending, then
+  if (state == 0) { // pending
+    // a. Append fulfillReaction to promise.[[PromiseFulfillReactions]].
+    const fulfillReactions: any[] = promise[2];
+    Porffor.fastPush(fulfillReactions, fulfillReaction);
+
+    // b. Append rejectReaction to promise.[[PromiseRejectReactions]].
+    const rejectReactions: any[] = promise[3];
+    Porffor.fastPush(rejectReactions, rejectReaction);
+  } else if (state == 1) { // fulfilled
+    // 10. Else if promise.[[PromiseState]] is fulfilled, then
+    // a. Let value be promise.[[PromiseResult]].
+    const value: any = promise[0];
+
+    // b. Let fulfillJob be NewPromiseReactionJob(fulfillReaction, value).
+    // c. Perform HostEnqueuePromiseJob(fulfillJob.[[Job]], fulfillJob.[[Realm]]).
+    __ecma262_HostEnqueuePromiseJob(__ecma262_NewPromiseReactionJob(fulfillReaction, value));
+  } else { // rejected
+    // 11. Else,
+    // a. Assert: The value of promise.[[PromiseState]] is rejected.
+    // todo
+
+    // b. Let reason be promise.[[PromiseResult]].
+    const reason: any = promise[0];
+
+    // c. If promise.[[PromiseIsHandled]] is false, perform HostPromiseRejectionTracker(promise, "handle").
+    // unimplemented
+
+    // d. Let rejectJob be NewPromiseReactionJob(rejectReaction, reason).
+    // e. Perform HostEnqueuePromiseJob(rejectJob.[[Job]], rejectJob.[[Realm]]).
+    __ecma262_HostEnqueuePromiseJob(__ecma262_NewPromiseReactionJob(rejectReaction, reason));
+  }
+
+  const pro: Promise = outPromise;
+  return pro;
+};
+
+export const __Promise_prototype_toString = (_this: any) => {
+  const str: bytestring = '[object Promise]';
+  return str;
+};
+
+export const __Promise_prototype_toLocaleString = (_this: any) => __Promise_prototype_toString(_this);