rooklang 0.0.0-stage → 0.3.0

package/dist/codegen/functions.js

@@ -0,0 +1,170 @@
+import { isIterator } from "../iterators.js";
+import { declarationsOf, findDefers } from "./analysis.js";
+import { WebComponentEmitter } from "./web-components.js";
+import { ARROW, POSTFIX } from "./syntax.js";
+/** Function bodies and `defer`. */
+export class FunctionEmitter extends WebComponentEmitter {
+    /** Parameters and body of a function, method or func literal. */
+    func(params, body) {
+        const defers = findDefers(body);
+        const mode = defers.length === 0
+            ? 'none'
+            : defers.every((defer) => body.body.includes(defer))
+                ? 'try'
+                : 'stack';
+        return this.withFunction(mode, params, () => {
+            // An iterator is a generator: it takes no function, and `yield(v)` yields (calls.ts).
+            this.fn.iterator = isIterator(params);
+            const paramList = this.fn.iterator ? '' : this.params(params);
+            const text = this.block(() => {
+                this.withScope(declarationsOf(body.body), () => {
+                    if (mode === 'try') {
+                        this.statementsWithDefers(body.body);
+                    }
+                    else if (mode === 'stack') {
+                        this.helpers.add('runDeferred');
+                        this.line('const $$defer = [];');
+                        const statements = this.block(() => this.statements(body.body));
+                        const finalizer = this.block(() => this.line('$$runDeferred($$defer);'));
+                        this.line(`try ${statements} finally ${finalizer}`);
+                    }
+                    else {
+                        this.statements(body.body);
+                    }
+                });
+            });
+            return [paramList, text];
+        });
+    }
+    /**
+     * `effect { ... }` becomes a function, `$$effect5`, which runs once the markup is created and
+     * again after the updates of what it reads (see EarlyReturnEmitter). What it defers is run before
+     * it runs again, and when `{if}`, `{switch}` or `{for}` removes the component.
+     */
+    effectStatement(node) {
+        const id = this.nextId();
+        const name = `$$effect${id}`;
+        const cleanups = findDefers(node.body).length > 0 ? `$$cleanups${id}` : null;
+        this.inHandler++;
+        try {
+            const body = this.withRendering(0, () => cleanups === null ? this.func([], node.body)[1] : this.effectBody(node.body, cleanups));
+            if (cleanups !== null)
+                this.line(`const ${cleanups} = [];`);
+            this.line(`const ${name} = () => ${body};`);
+        }
+        finally {
+            this.inHandler--;
+        }
+        this.addEffect({ name, node, cleanups });
+    }
+    effectBody(body, cleanups) {
+        return this.withFunction('effect', [], () => {
+            this.fn.deferList = cleanups;
+            this.helpers.add('runDeferred');
+            return this.block(() => this.withScope(declarationsOf(body.body), () => {
+                this.line(`$$runDeferred(${cleanups}.splice(0));`);
+                this.statements(body.body);
+            }));
+        });
+    }
+    /** A `defer` in 'stack' and 'effect' modes; in 'try' mode statementsWithDefers handles them. */
+    deferStatement(node) {
+        const { body } = node;
+        if (body.kind === 'BlockStatement') {
+            const block = this.block(() => this.blockStatements(body.body));
+            this.line(`${this.fn.deferList}.push(() => ${block});`);
+            return;
+        }
+        // Temporaries for the arguments go into a block so that each loop iteration gets its own.
+        const lines = this.capture(() => this.line(`${this.fn.deferList}.push(() => ${this.deferredCall(body)});`));
+        if (lines.length === 1)
+            this.line(lines[0].trimStart());
+        else
+            this.line(`{\n${lines.join('\n')}\n${this.indent()}}`);
+    }
+    /** Statements of a body whose `defer`s are all at its top level: one try/finally per `defer`. */
+    statementsWithDefers(list) {
+        const index = list.findIndex((statement) => statement.kind === 'DeferStatement');
+        if (index === -1) {
+            this.statements(list);
+            return;
+        }
+        this.statements(list.slice(0, index));
+        const runDeferred = this.prepareDeferred(list[index]);
+        const rest = list.slice(index + 1);
+        if (rest.length === 0) {
+            // Nothing can happen between the `defer` and the end of the function.
+            runDeferred();
+            return;
+        }
+        const body = this.block(() => this.statementsWithDefers(rest));
+        this.line(`try ${body} finally ${this.block(runDeferred)}`);
+    }
+    /**
+     * Go evaluates the function and arguments of a deferred call at the `defer` statement. Values
+     * that cannot change in between are used as they are; others are saved to temporaries here.
+     * Returns a function that writes the deferred code.
+     */
+    prepareDeferred(node) {
+        const { body } = node;
+        if (body.kind === 'BlockStatement')
+            return () => this.blockStatements(body.body);
+        const call = this.deferredCall(body);
+        return () => this.line(`${call};`);
+    }
+    deferredCall(call) {
+        const { callee } = call;
+        let target;
+        if (callee.kind === 'MemberExpression') {
+            const object = this.memberObject(callee.object, (o) => this.stable(o, POSTFIX));
+            target = `${object}${callee.optional ? '?.' : '.'}${callee.property.name}`;
+        }
+        else if (callee.kind === 'IndexExpression') {
+            const object = this.memberObject(callee.object, (o) => this.stable(o, POSTFIX));
+            target = `${object}${callee.optional ? '?.[' : '['}${this.stable(callee.index, 0)}]`;
+        }
+        else if (this.isBuiltinError(callee)) {
+            target = 'Error';
+        }
+        else {
+            target = this.stable(callee, POSTFIX);
+        }
+        const args = call.arguments.map((arg) => arg.kind === 'SpreadElement'
+            ? `...${this.stable(arg.argument, ARROW)}`
+            : this.stable(arg, ARROW));
+        return `${target}${call.optional ? '?.' : ''}(${args.join(', ')})`;
+    }
+    /** The expression itself if its value cannot change before the deferred call runs. */
+    stable(node, precedence) {
+        if (this.isStable(node))
+            return this.expression(node, precedence);
+        const temp = this.temp();
+        this.line(`const ${temp} = ${this.expression(node, ARROW)};`);
+        return temp;
+    }
+    isStable(node) {
+        switch (node.kind) {
+            case 'NumberLiteral':
+            case 'StringLiteral':
+            case 'BooleanLiteral':
+            case 'NullLiteral':
+            case 'ThisExpression':
+            case 'SuperExpression':
+                return true;
+            case 'TemplateLiteral':
+                return node.expressions.every((expression) => this.isStable(expression));
+            case 'Identifier': {
+                const kind = this.lookup(node.name);
+                // A derived value is computed again by the updates, not by the code.
+                if (kind === 'derived')
+                    return false;
+                if (kind === 'let' || kind === 'state' || kind === 'param' || kind === 'catch') {
+                    return !this.assigned.has(node.name);
+                }
+                return true;
+            }
+            default:
+                return false;
+        }
+    }
+}

package/dist/codegen/go-helpers.d.ts

@@ -0,0 +1,9 @@
+export type GoHelper = 'go' | 'goLocal' | 'goFor' | 'shared' | 'serve' | 'cancel';
+export declare const GO_HELPERS: Readonly<Record<GoHelper, readonly string[]>>;
+/**
+ * The start of a worker of a module: a Web Worker, or a worker thread of Node. Node takes only the
+ * path of a `file:` URL, without the query of `app.rk?goroutines`, so its worker starts with a
+ * module that imports the whole URL. An absolute URL, such as the Blob of the playground, is used
+ * as it is.
+ */
+export declare function startWorker(url: string): string[];

package/dist/codegen/go-helpers.js

@@ -0,0 +1,307 @@
+// The helpers of `go`: the pool of workers of the program, and the side of the worker. They work
+// with Web Workers and with the worker threads of Node, whose API differs: `on("message")` instead
+// of `onmessage`, and `unref()`, so that idle workers do not keep the program running.
+export const GO_HELPERS = {
+    /** `go` in a module: a call in a worker of the pool, started by $$startWorker of the module. */
+    go: [
+        'function $$go(name, args) {',
+        '  return (globalThis[Symbol.for("rook.goroutines")] ??= $$pool()).call(',
+        '    $$startWorker,',
+        '    name,',
+        '    $$copy(args, true),',
+        '  );',
+        '}',
+        '',
+        '// The workers of the program, shared by its modules: up to one per processor. Each runs the worker',
+        '// module of one module, `start`. Calls wait in one queue and go to a worker of their module that is',
+        '// free: one whose thread is not running code, though its earlier calls may wait in `await`. A',
+        '// worker that is still busy keeps its calls for later; an idle worker of another module makes room',
+        '// for a new one, unless it keeps channels.',
+        'function $$pool() {',
+        '  const size = globalThis.navigator?.hardwareConcurrency ?? 4;',
+        '  const registry = $$registry();',
+        '  const workers = [];',
+        '  const queue = [];',
+        '  const calls = new Map();',
+        '  let ids = 0;',
+        '  // A worker without calls lets the program end, unless something here waits for it.',
+        '  const unref = (worker) => {',
+        '    if (worker.calls === 0 && !(registry.pins.get(worker.key) > 0)) worker.thread.unref?.();',
+        '  };',
+        '  registry.idle = (key) => {',
+        '    const worker = workers.find((each) => each.key === key);',
+        '    if (worker) unref(worker);',
+        '  };',
+        '  const send = (worker, call) => {',
+        '    worker.busy = true;',
+        '    worker.calls++;',
+        '    worker.thread.ref?.();',
+        '    call.worker = worker;',
+        '    calls.set(call.id, call);',
+        '    $$post(worker.key, { call: call.id, name: call.name, args: call.args });',
+        '    call.args = null;',
+        '  };',
+        '  const dispatch = () => {',
+        '    const starting = new Map();',
+        '    for (const worker of workers) {',
+        '      if (!worker.key) starting.set(worker.start, (starting.get(worker.start) ?? 0) + 1);',
+        '    }',
+        '    for (let i = 0; i < queue.length; i++) {',
+        '      const call = queue[i];',
+        '      let free = null;',
+        '      for (const worker of workers) {',
+        '        if (worker.start !== call.start || !worker.key || worker.busy) continue;',
+        '        if (!free || worker.calls < free.calls) free = worker;',
+        '      }',
+        '      // A free worker without calls; else a new worker; else one whose calls wait in await.',
+        '      if (free?.calls === 0 || (free && workers.length >= size)) {',
+        '        queue.splice(i--, 1);',
+        '        send(free, call);',
+        '      } else if (starting.get(call.start) > 0) {',
+        '        starting.set(call.start, starting.get(call.start) - 1);',
+        '      } else if (workers.length < size || retire(call.start)) {',
+        '        add(call.start);',
+        '      } else {',
+        '        // It waits for a busy worker of its module, which may have let go of the program when',
+        '        // its last call returned: the program runs on until that worker is free and takes it.',
+        '        for (const worker of workers) if (worker.start === call.start && worker.key) worker.thread.ref?.();',
+        '      }',
+        '    }',
+        '  };',
+        '  const retire = (start) => {',
+        '    const idle = workers.find(',
+        '      (worker) => worker.key && worker.start !== start && !worker.busy && worker.calls === 0 && !worker.owns,',
+        '    );',
+        '    if (!idle) return false;',
+        '    idle.thread.terminate();',
+        '    remove(idle, null);',
+        '    return true;',
+        '  };',
+        '  // A worker that stopped: its calls fail, and the threads that talked to it forget it.',
+        '  const remove = (worker, error) => {',
+        '    workers.splice(workers.indexOf(worker), 1);',
+        '    for (const [id, call] of calls) {',
+        '      if (call.worker !== worker) continue;',
+        '      calls.delete(id);',
+        '      call.reject(error);',
+        '    }',
+        '    if (worker.key) {',
+        '      $$gone(worker.key);',
+        '      for (const other of workers) other.key && other.thread.postMessage({ gone: worker.key });',
+        '    }',
+        '  };',
+        '  const fail = (worker, error) => {',
+        '    remove(worker, error);',
+        '    dispatch();',
+        '  };',
+        '  const receive = (worker, data) => {',
+        '    if ("op" in data || "answer" in data) return $$incoming(worker.key, data);',
+        '    if ("hello" in data) {',
+        '      worker.key = data.hello;',
+        '      $$connect(worker.key, worker.thread, false);',
+        '      worker.thread.postMessage({ init: registry.key });',
+        '      // Workers talk to each other through ports of their own, also while this thread is busy.',
+        '      for (const other of workers) {',
+        '        if (other === worker || !other.key) continue;',
+        '        const { port1, port2 } = new MessageChannel();',
+        '        worker.thread.postMessage({ port: other.key, through: port1 }, [port1]);',
+        '        other.thread.postMessage({ port: worker.key, through: port2 }, [port2]);',
+        '      }',
+        '      worker.busy = false;',
+        '      unref(worker);',
+        '    } else if ("free" in data) {',
+        '      worker.busy = false;',
+        '      worker.owns = data.owns;',
+        '    } else if ("returned" in data) {',
+        '      $$adopt(data);',
+        '      const call = calls.get(data.returned);',
+        '      calls.delete(data.returned);',
+        '      worker.owns = data.owns;',
+        '      worker.calls--;',
+        '      unref(worker);',
+        '      if ("error" in data) call?.reject(data.error);',
+        '      else call?.resolve(data.value);',
+        '    }',
+        '    dispatch();',
+        '    // A worker that a waiting call held on to, now free and without a call, lets go again.',
+        '    if ("free" in data) unref(worker);',
+        '  };',
+        '  const add = (start) => {',
+        '    const worker = { start, key: null, thread: null, busy: true, calls: 0, owns: false };',
+        '    workers.push(worker);',
+        '    start().then(',
+        '      (thread) => {',
+        '        worker.thread = thread;',
+        '        if (thread.on) {',
+        '          thread.on("message", (data) => receive(worker, data));',
+        '          thread.on("error", (error) => fail(worker, error));',
+        '        } else {',
+        '          thread.onmessage = (event) => receive(worker, event.data);',
+        '          thread.onerror = (event) => fail(worker, new Error(event.message ?? "a worker failed"));',
+        '        }',
+        '      },',
+        '      (error) => {',
+        '        remove(worker, error);',
+        '        for (const call of queue.filter((each) => each.start === start)) {',
+        '          queue.splice(queue.indexOf(call), 1);',
+        '          call.reject(error);',
+        '        }',
+        '      },',
+        '    );',
+        '  };',
+        '  const tasks = new WeakMap();',
+        '  return {',
+        '    call: (start, name, args) => {',
+        '      const call = { id: ids++, start, name, args, resolve: null, reject: null, worker: null };',
+        '      const task = new Promise((resolve, reject) => Object.assign(call, { resolve, reject }));',
+        '      tasks.set(task, call);',
+        '      queue.push(call);',
+        '      dispatch();',
+        '      return task;',
+        '    },',
+        '    // A call that waits leaves the queue; a worker cannot stop a call, so the worker stops, and',
+        '    // the other calls in it fail too.',
+        '    cancel: (task) => {',
+        '      const call = tasks.get(task);',
+        '      tasks.delete(task);',
+        '      if (!call || (!queue.includes(call) && !calls.has(call.id))) return;',
+        '      task.catch(() => {});',
+        '      if (queue.includes(call)) {',
+        '        queue.splice(queue.indexOf(call), 1);',
+        '        return call.reject(new Error("goroutine cancelled"));',
+        '      }',
+        '      calls.delete(call.id);',
+        '      call.reject(new Error("goroutine cancelled"));',
+        '      call.worker.thread.terminate();',
+        '      remove(call.worker, new Error("the worker of the goroutine stopped: another goroutine in it was cancelled"));',
+        '      dispatch();',
+        '    },',
+        '  };',
+        '}',
+    ],
+    /** `go` inside a goroutine: the function runs in the same worker, with copies of the arguments. */
+    goLocal: [
+        'function $$go(fn, args) {',
+        '  const copies = $$copy(args);',
+        '  const run = typeof fn === "function" ? fn : $$goroutines[fn];',
+        '  let cancel;',
+        '  const cancelled = new Promise((_, reject) => (cancel = reject));',
+        '  const task = Promise.race([cancelled, Promise.resolve().then(() => cancel && run(...copies))]);',
+        '  $$registry().cancels.set(task, () => {',
+        '    task.catch(() => {});',
+        '    cancel(new Error("goroutine cancelled"));',
+        '    cancel = null;',
+        '  });',
+        '  return task;',
+        '}',
+    ],
+    goFor: [
+        '// `go for`: the array is split into parts, one per processor, each part runs as a goroutine, and',
+        '// the loop waits for all of them. A typed array on a SharedArrayBuffer is shared with the workers,',
+        '// which write into it; other parts are copies, moved to the workers and back into the array.',
+        'async function $$goFor(name, items, ...captured) {',
+        '  const count = Math.min(globalThis.navigator?.hardwareConcurrency ?? 4, items.length);',
+        '  const shared =',
+        '    typeof SharedArrayBuffer === "function" && items.buffer instanceof SharedArrayBuffer;',
+        '  const parts = [];',
+        '  for (let k = 0; k < count; k++) {',
+        '    const from = Math.floor((items.length * k) / count);',
+        '    const to = Math.floor((items.length * (k + 1)) / count);',
+        '    const part = shared ? items.subarray(from, to) : items.slice(from, to);',
+        '    if (ArrayBuffer.isView(part) && !shared) $$transfer(part);',
+        '    parts.push(',
+        '      $$go(name, [part, from, ...captured]).then((written) => {',
+        '        if (written === undefined || shared) return;',
+        '        if (ArrayBuffer.isView(items)) items.set(written, from);',
+        '        else for (let i = 0; i < written.length; i++) items[from + i] = written[i];',
+        '      }),',
+        '    );',
+        '  }',
+        '  await Promise.all(parts);',
+        '}',
+    ],
+    shared: [
+        '// `make([]T, n, shared)`: the memory of a typed array that the workers of `go for` write into,',
+        '// without copies. A page has SharedArrayBuffer only with cross-origin isolation.',
+        'function $$shared(bytes) {',
+        '  if (typeof SharedArrayBuffer !== "function") {',
+        '    throw new Error(',
+        '      "make(..., shared) needs SharedArrayBuffer, which a page has only with cross-origin isolation: the headers Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp",',
+        '    );',
+        '  }',
+        '  return new SharedArrayBuffer(bytes);',
+        '}',
+    ],
+    serve: [
+        '// The worker: runs the calls that the pool sends and sends back their results or errors. Once the',
+        '// thread is free again, it says so, and the pool may send another call.',
+        'async function $$serve(functions) {',
+        '  const threads = "node:worker_threads";',
+        '  const port =',
+        '    typeof postMessage === "function"',
+        '      ? globalThis',
+        '      : (await import(/* @vite-ignore */ threads)).parentPort;',
+        '  const registry = $$registry();',
+        '  // The port to the main thread keeps the worker running.',
+        '  registry.idle = (key) => key !== registry.main && registry.ports.get(key)?.unref?.();',
+        '  port.postMessage({ hello: registry.key });',
+        '  const free = () => port.postMessage({ free: true, owns: registry.states.size > 0 });',
+        '  const receive = async (data) => {',
+        '    if ("op" in data || "answer" in data) return $$incoming(registry.main, data);',
+        '    if ("init" in data) {',
+        '      registry.main = data.init;',
+        '      return $$connect(data.init, port, false);',
+        '    }',
+        '    if ("port" in data) return $$connect(data.port, data.through, true);',
+        '    if ("gone" in data) return $$gone(data.gone);',
+        '    setTimeout(free);',
+        '    $$adopt(data.args);',
+        '    const { main } = registry;',
+        '    try {',
+        '      const value = await functions[data.name](...data.args);',
+        '      $$post(main, { returned: data.call, value, owns: registry.states.size > 0 });',
+        '    } catch (error) {',
+        '      try {',
+        '        $$post(main, { returned: data.call, error, owns: registry.states.size > 0 });',
+        '      } catch {',
+        '        $$post(main, { returned: data.call, error: new Error(String(error)), owns: true });',
+        '      }',
+        '    }',
+        '  };',
+        '  if (port.on) port.on("message", receive);',
+        '  else port.onmessage = (event) => receive(event.data);',
+        '}',
+    ],
+    cancel: [
+        '// `cancel(task)`: stops a goroutine of `go`, whose Promise fails with "goroutine cancelled". A call',
+        '// in a worker stops with its worker; inside a goroutine, `go` runs in the same worker, so its',
+        '// Promise fails but code that has started goes on.',
+        'function $$cancel(task) {',
+        '  globalThis[Symbol.for("rook.goroutines")]?.cancel(task);',
+        '  $$registry().cancels.get(task)?.();',
+        '}',
+    ],
+};
+/**
+ * The start of a worker of a module: a Web Worker, or a worker thread of Node. Node takes only the
+ * path of a `file:` URL, without the query of `app.rk?goroutines`, so its worker starts with a
+ * module that imports the whole URL. An absolute URL, such as the Blob of the playground, is used
+ * as it is.
+ */
+export function startWorker(url) {
+    const base = /^[a-z][a-z\d+.-]*:/i.test(url) ? '' : ', import.meta.url';
+    const workerUrl = `new URL(${JSON.stringify(url)}${base})`;
+    return [
+        'async function $$startWorker() {',
+        '  if (typeof Worker === "function") {',
+        `    return new Worker(${workerUrl}, { type: "module" });`,
+        '  }',
+        '  const threads = "node:worker_threads";',
+        '  const { Worker: NodeWorker } = await import(/* @vite-ignore */ threads);',
+        // Vite bundles the Web Worker; this URL is only for Node.
+        `  const url = new URL(/* @vite-ignore */ ${JSON.stringify(url)}${base});`,
+        '  const code = `import ${JSON.stringify(url.href)};`;',
+        '  return new NodeWorker(new URL(`data:text/javascript,${encodeURIComponent(code)}`));',
+        '}',
+    ];
+}

package/dist/codegen/helpers.d.ts

@@ -0,0 +1,10 @@
+import { type ChanHelper } from './chan-helpers.ts';
+import { type GoHelper } from './go-helpers.ts';
+import { type SelectHelper } from './select-helpers.ts';
+import { type ThreadHelper } from './thread-helpers.ts';
+export type Helper = GoHelper | ChanHelper | SelectHelper | ThreadHelper | 'runDeferred' | 'values' | 'append' | 'attribute' | 'content' | 'branches' | 'dynamic' | 'list' | 'owner' | 'mount' | 'style' | 'element' | 'svgElement';
+/** Predeclared functions of goroutines and channels, by the helpers that define them. */
+export declare const PREDECLARED: Readonly<Record<string, Helper>>;
+/** Helpers that use other helpers. */
+export declare const HELPER_NEEDS: Readonly<Partial<Record<Helper, readonly Helper[]>>>;
+export declare const HELPERS: Readonly<Record<Helper, readonly string[]>>;