rooklang 0.0.0-stage → 0.3.0

package/dist/codegen/helpers.js

@@ -0,0 +1,356 @@
+import { CHAN_HELPERS } from "./chan-helpers.js";
+import { GO_HELPERS } from "./go-helpers.js";
+import { SELECT_HELPERS } from "./select-helpers.js";
+import { THREAD_HELPERS } from "./thread-helpers.js";
+/** Predeclared functions of goroutines and channels, by the helpers that define them. */
+export const PREDECLARED = {
+    close: 'chan',
+    transfer: 'threads',
+    after: 'timers',
+    tick: 'timers',
+    cancel: 'cancel',
+};
+/** Helpers that use other helpers. */
+export const HELPER_NEEDS = {
+    go: ['threads'],
+    goFor: ['threads'],
+    goLocal: ['threads'],
+    serve: ['threads'],
+    chan: ['threads', 'select'],
+    timers: ['chan'],
+    cancel: ['threads'],
+    select: ['chan'],
+    owner: ['runDeferred'],
+    mount: ['owner'],
+    content: ['owner'],
+    branches: ['owner'],
+    dynamic: ['owner'],
+    list: ['owner'],
+};
+export const HELPERS = {
+    ...GO_HELPERS,
+    ...CHAN_HELPERS,
+    ...SELECT_HELPERS,
+    ...THREAD_HELPERS,
+    /** `for v in x` over an untyped value: a Map gives its values, as a typed one does. */
+    values: [
+        'function $$values(iterable) {',
+        "  if (typeof iterable === 'function') return iterable();",
+        '  return iterable instanceof Map ? iterable.values() : iterable;',
+        '}',
+    ],
+    /** Runs deferred calls in reverse order; every call runs even if an earlier one throws. */
+    runDeferred: [
+        'function $$runDeferred(deferred) {',
+        '  let failure;',
+        '  for (let i = deferred.length - 1; i >= 0; i--) {',
+        '    try {',
+        '      deferred[i]();',
+        '    } catch (error) {',
+        '      failure = { error };',
+        '    }',
+        '  }',
+        '  if (failure) throw failure.error;',
+        '}',
+    ],
+    /**
+     * Owners of markup that `{if}`, `{switch}` and `{for}` may remove: the functions returned by the
+     * `mount()` of its components, and the removal of the blocks inside it, run when it is removed.
+     * The current owner is shared by the modules of a page, since the blocks of one module may hold
+     * the components of another.
+     */
+    owner: [
+        'const $$owner = Symbol.for("rook.owner");',
+        '',
+        'function $$owned(create) {',
+        '  const owner = { removed: false, cleanups: [] };',
+        '  const parent = globalThis[$$owner];',
+        '  globalThis[$$owner] = owner;',
+        '  let result;',
+        '  try {',
+        '    result = create();',
+        '  } finally {',
+        '    globalThis[$$owner] = parent;',
+        '  }',
+        '  const remove = () => {',
+        '    if (owner.removed) return;',
+        '    owner.removed = true;',
+        '    $$runDeferred(owner.cleanups);',
+        '  };',
+        '  return [result, remove];',
+        '}',
+        '',
+        'function $$onRemove(cleanup) {',
+        '  globalThis[$$owner]?.cleanups.push(cleanup);',
+        '}',
+    ],
+    /**
+     * `mount() { ... }` of a component: runs when its markup is in the document. That is checked
+     * after the code that creates the component; markup that is not in the document yet is waited
+     * for with a MutationObserver, which watches only while some markup waits. Markup that its
+     * owner removes before that never mounts. The function `mount` returns runs when the owner is
+     * removed.
+     */
+    mount: [
+        'const $$waiting = new Set();',
+        'let $$observer = null;',
+        '',
+        'function $$mount(node, mount) {',
+        '  const entry = { node, mount, owner: globalThis[$$owner] };',
+        '  entry.owner?.cleanups.push(() => $$waiting.delete(entry));',
+        '  queueMicrotask(() => $$tryMount(entry));',
+        '}',
+        '',
+        'function $$tryMount(entry) {',
+        '  if (entry.owner?.removed) return;',
+        '  const node = entry.node();',
+        '  if (node != null && !node.isConnected) {',
+        '    $$waiting.add(entry);',
+        '    if (!$$observer) {',
+        '      $$observer = new MutationObserver($$mountWaiting);',
+        '      $$observer.observe(node.ownerDocument ?? document, { childList: true, subtree: true });',
+        '    }',
+        '    return;',
+        '  }',
+        '  const cleanup = entry.mount();',
+        '  if (typeof cleanup === "function") entry.owner?.cleanups.push(cleanup);',
+        '}',
+        '',
+        'function $$mountWaiting() {',
+        '  for (const entry of $$waiting) {',
+        '    if (!entry.node().isConnected) continue;',
+        '    $$waiting.delete(entry);',
+        '    $$tryMount(entry);',
+        '  }',
+        '  if ($$waiting.size === 0) {',
+        '    $$observer.disconnect();',
+        '    $$observer = null;',
+        '  }',
+        '}',
+    ],
+    /** Appends element content whose type is not known: null adds nothing, arrays add each item. */
+    append: [
+        'function $$append(parent, value) {',
+        '  if (value == null || value === false) return;',
+        '  if (Array.isArray(value)) {',
+        '    for (const item of value) $$append(parent, item);',
+        '  } else {',
+        '    parent.append(value);',
+        '  }',
+        '}',
+    ],
+    /**
+     * Nodes of markup that change, `{list}` or `{ok ? <b /> : null}`: they are kept before an end
+     * marker. Nodes that stay are moved rather than created again. Returns the markers with the
+     * first nodes, to be inserted, and the update.
+     */
+    content: [
+        'function $$content(value) {',
+        '  const end = document.createTextNode("");',
+        '  const fragment = document.createDocumentFragment();',
+        '  fragment.append(end);',
+        '  let nodes = [];',
+        '  let remove;',
+        '  const update = () => {',
+        '    const next = [];',
+        '    const add = (item) => {',
+        '      if (item == null || item === false) return;',
+        '      if (Array.isArray(item)) {',
+        '        for (const each of item) add(each);',
+        '      } else if (item.nodeType === 11) {',
+        '        next.push(...item.childNodes);',
+        '      } else {',
+        '        next.push(typeof item === "object" ? item : document.createTextNode(String(item)));',
+        '      }',
+        '    };',
+        '    const [created, removeCreated] = $$owned(value);',
+        '    add(created);',
+        '    remove?.();',
+        '    remove = removeCreated;',
+        '    const kept = new Set(next);',
+        '    for (const node of nodes) if (!kept.has(node)) node.remove();',
+        '    end.before(...next);',
+        '    nodes = next;',
+        '  };',
+        '  update();',
+        '  $$onRemove(() => remove?.());',
+        '  return [fragment, update];',
+        '}',
+    ],
+    /**
+     * `{if ...}` and `{switch ...}` in markup: shows the block that `choose` picks (-1 for none)
+     * between two markers. The block is created again only when the choice changes; otherwise it is
+     * updated.
+     */
+    branches: [
+        'function $$branches(choose, blocks) {',
+        '  const start = document.createTextNode("");',
+        '  const end = document.createTextNode("");',
+        '  const fragment = document.createDocumentFragment();',
+        '  fragment.append(start, end);',
+        '  let current = null;',
+        '  let update;',
+        '  let remove;',
+        '  const render = () => {',
+        '    const next = choose();',
+        '    if (next === current) {',
+        '      update?.();',
+        '      return;',
+        '    }',
+        '    current = next;',
+        '    remove?.();',
+        '    while (start.nextSibling !== end) start.nextSibling.remove();',
+        '    update = undefined;',
+        '    remove = undefined;',
+        '    if (next >= 0) {',
+        '      const [[content, blockUpdate], removeBlock] = $$owned(blocks[next]);',
+        '      end.before(content);',
+        '      update = blockUpdate;',
+        '      remove = removeBlock;',
+        '    }',
+        '  };',
+        '  render();',
+        '  $$onRemove(() => remove?.());',
+        '  return [fragment, render];',
+        '}',
+    ],
+    /**
+     * `<Page />` whose component is a value that changes: when it does, the block that `create`
+     * makes with it is created again between two markers; otherwise the block is updated.
+     */
+    dynamic: [
+        'function $$dynamic(component, create) {',
+        '  const start = document.createTextNode("");',
+        '  const end = document.createTextNode("");',
+        '  const fragment = document.createDocumentFragment();',
+        '  fragment.append(start, end);',
+        '  let current;',
+        '  let update;',
+        '  let remove;',
+        '  const render = () => {',
+        '    const next = component();',
+        '    if (remove && next === current) {',
+        '      update?.();',
+        '      return;',
+        '    }',
+        '    current = next;',
+        '    remove?.();',
+        '    while (start.nextSibling !== end) start.nextSibling.remove();',
+        '    const [[content, blockUpdate], removeBlock] = $$owned(() => create(next));',
+        '    end.before(content);',
+        '    update = blockUpdate;',
+        '    remove = removeBlock;',
+        '  };',
+        '  render();',
+        '  $$onRemove(() => remove?.());',
+        '  return [fragment, render];',
+        '}',
+    ],
+    /**
+     * `{for item in items { ... }}` in markup: a block for each item, between its own markers. On
+     * updates the blocks are found again by the item itself: blocks of items that stay are updated
+     * and moved into place, others are created or removed.
+     */
+    list: [
+        'function $$list(items, create) {',
+        '  const end = document.createTextNode("");',
+        '  const fragment = document.createDocumentFragment();',
+        '  fragment.append(end);',
+        '  let blocks = [];',
+        '  const nodesOf = (block) => {',
+        '    const nodes = [];',
+        '    for (let node = block.start; node !== block.end; node = node.nextSibling) nodes.push(node);',
+        '    nodes.push(block.end);',
+        '    return nodes;',
+        '  };',
+        '  const update = () => {',
+        '    const old = new Map();',
+        '    for (const block of blocks) {',
+        '      const same = old.get(block.item);',
+        '      if (same) same.push(block);',
+        '      else old.set(block.item, [block]);',
+        '    }',
+        '    const next = [];',
+        '    let index = 0;',
+        '    for (const item of items()) {',
+        '      let block = old.get(item)?.shift();',
+        '      if (block) {',
+        '        block.update?.(index);',
+        '      } else {',
+        '        const [[content, blockUpdate], remove] = $$owned(() => create(item, index));',
+        '        block = { item, start: document.createTextNode(""), end: document.createTextNode("") };',
+        '        block.update = blockUpdate;',
+        '        block.remove = remove;',
+        '        block.content = document.createDocumentFragment();',
+        '        block.content.append(block.start, content, block.end);',
+        '      }',
+        '      next.push(block);',
+        '      index++;',
+        '    }',
+        '    for (const same of old.values()) {',
+        '      for (const block of same) {',
+        '        block.remove();',
+        '        for (const node of nodesOf(block)) node.remove();',
+        '      }',
+        '    }',
+        '    let before = end;',
+        '    for (let i = next.length - 1; i >= 0; i--) {',
+        '      const block = next[i];',
+        '      if (block.content) {',
+        '        before.before(block.content);',
+        '        block.content = null;',
+        '      } else if (block.end.nextSibling !== before) {',
+        '        before.before(...nodesOf(block));',
+        '      }',
+        '      before = block.start;',
+        '    }',
+        '    blocks = next;',
+        '  };',
+        '  update();',
+        '  $$onRemove(() => {',
+        '    for (const block of blocks) block.remove();',
+        '  });',
+        '  return [fragment, update];',
+        '}',
+    ],
+    /** Creates an element with its properties and the attributes that are set with setAttribute. */
+    element: [
+        'function $$element(tag, properties, attributes) {',
+        '  const element = Object.assign(document.createElement(tag), properties);',
+        '  for (const name in attributes) element.setAttribute(name, attributes[name]);',
+        '  return element;',
+        '}',
+    ],
+    /** Creates an SVG element with its attributes. */
+    svgElement: [
+        'function $$svgElement(tag, attributes) {',
+        '  const element = document.createElementNS("http://www.w3.org/2000/svg", tag);',
+        '  for (const name in attributes) element.setAttribute(name, attributes[name]);',
+        '  return element;',
+        '}',
+    ],
+    /** Sets an attribute whose value may be null: then the attribute is removed. */
+    attribute: [
+        'function $$attribute(element, name, value) {',
+        '  if (value == null) element.removeAttribute(name);',
+        '  else element.setAttribute(name, value);',
+        '}',
+    ],
+    /**
+     * Adds the CSS of a component to the page once: modules that inline the same component add it
+     * with the same id. `$$styles` keeps the CSS of the module for the shadow roots of its web
+     * components, which the page's styles do not reach.
+     */
+    style: [
+        'const $$styles = [];',
+        '',
+        'function $$style(id, css) {',
+        '  $$styles.push(css);',
+        '  if (document.getElementById(id)) return;',
+        '  const style = document.createElement("style");',
+        '  style.id = id;',
+        '  style.textContent = css;',
+        '  document.head.append(style);',
+        '}',
+    ],
+};

package/dist/codegen/imported.d.ts

@@ -0,0 +1,38 @@
+import type * as ast from '../ast.ts';
+import type { Type } from '../checker/types.ts';
+import { type CopyListener } from '../decorator-copy.ts';
+import type { InlinePackage } from '../inline-packages.ts';
+import { type Root } from '../refs.ts';
+export interface ImportedComponent {
+    node: ast.ComponentDeclaration;
+    /** What inlining needs; null when the component can only be called. */
+    inline: InlinePackage | null;
+    /** The types of the expressions of its module. */
+    types: WeakMap<ast.Expression, Type> | null;
+    /** The element at the top of what it creates, found in its module, or why it is not known. */
+    root: Root;
+}
+/** An inlined component of another module, with the components it brings, by their tags here. */
+export interface LocalizedPackage {
+    /** The tags here of the components of the other module. */
+    tags: Map<string, string>;
+    inline: Map<string, ast.ComponentDeclaration>;
+    /** Components it calls, with the names of their functions here and the elements at their top. */
+    functions: Map<string, {
+        node: ast.ComponentDeclaration;
+        name: string;
+        root: Root;
+    }>;
+    /** The hidden names it imports: as exported there, as named here. */
+    imports: [string, string][];
+}
+/**
+ * The package of a component or a decorator `root` of another module, ready to be inlined here.
+ * `name` is the prefix of its names here: the name it is imported as.
+ */
+export declare function localize(name: string, root: string, found: InlinePackage, copied: CopyListener): LocalizedPackage;
+/**
+ * `export { PREFIX as $$Card$PREFIX }` and the like: what the modules that inline the exported
+ * components of this one import from it, by the name they are exported under.
+ */
+export declare function packageExports(packages: ReadonlyMap<string, InlinePackage>, jsName: (name: string) => string): Map<string, string>;

package/dist/codegen/imported.js

@@ -0,0 +1,71 @@
+import { renamer } from "../decorator-copy.js";
+import { decorate, decoratedName } from "../decorators.js";
+import { componentRoot } from "../refs.js";
+/**
+ * The package of a component or a decorator `root` of another module, ready to be inlined here.
+ * `name` is the prefix of its names here: the name it is imported as.
+ */
+export function localize(name, root, found, copied) {
+    const tag = (other) => (other === root ? name : `${name}$${other}`);
+    const tags = new Map([...found.components.keys(), ...found.functions.keys()].map((other) => [other, tag(other)]));
+    const prefixes = new Map([...found.decorators.keys()].map((other) => [other, `${name}$${other}`]));
+    const renames = new Map(found.moduleNames.map((used) => [used, decoratedName(name, used)]));
+    const copy = renamer(renames, copied, { tags, decorators: prefixes });
+    const inline = new Map();
+    const functions = new Map();
+    // Here the copy is not exported: it is inlined like a component of this module.
+    for (const [other, node] of found.components) {
+        const component = copy(decorate(node, found.decorators, copied, prefixes), new Set());
+        inline.set(tag(other), { ...component, exported: false });
+    }
+    // A copy of its own: the same component may be imported here directly too.
+    for (const [other, node] of found.functions) {
+        const root = packageRoot(found, other, new Set());
+        functions.set(tag(other), { node: { ...node }, name: `$$${tag(other)}`, root });
+    }
+    const imports = [
+        ...found.moduleNames.map((used) => [
+            decoratedName(root, used),
+            decoratedName(name, used),
+        ]),
+        ...[...found.decorators].flatMap(([other, source]) => source.moduleNames.map((used) => [
+            decoratedName(other, used),
+            decoratedName(prefixes.get(other), used),
+        ])),
+        ...[...found.functions.keys()].map((other) => [
+            `$$${other}`,
+            `$$${tag(other)}`,
+        ]),
+    ];
+    return { tags, inline, functions, imports };
+}
+/** The element at the top of what a component of a package creates, by its name there. */
+function packageRoot(found, name, seen) {
+    const node = found.components.get(name) ?? found.functions.get(name);
+    if (!node || seen.has(name))
+        return 'is not known in advance';
+    seen.add(name);
+    return componentRoot(decorate(node, found.decorators), (tag) => packageRoot(found, tag, seen));
+}
+/**
+ * `export { PREFIX as $$Card$PREFIX }` and the like: what the modules that inline the exported
+ * components of this one import from it, by the name they are exported under.
+ */
+export function packageExports(packages, jsName) {
+    const exports = new Map();
+    for (const [root, found] of packages) {
+        for (const used of found.moduleNames)
+            exports.set(decoratedName(root, used), jsName(used));
+        for (const [other, source] of found.decorators) {
+            for (const used of source.moduleNames) {
+                exports.set(decoratedName(other, used), jsName(used));
+            }
+        }
+        // An exported component's function is exported already.
+        for (const [other, node] of found.functions) {
+            if (!node.exported)
+                exports.set(`$$${other}`, `$$${other}`);
+        }
+    }
+    return exports;
+}

package/dist/codegen/js.d.ts

@@ -0,0 +1,20 @@
+import type * as ast from '../ast.ts';
+import type { JsOptions } from './emitter.ts';
+export type { JsOptions } from './emitter.ts';
+/** A component whose inlined copies add more lines than this to its module becomes a function. */
+export declare const INLINE_LIMIT = 100;
+/**
+ * A module whose code creates more elements than this creates them with $$element, which takes
+ * their attributes: its definition takes less than the statements it saves.
+ */
+export declare const ELEMENT_HELPER_LIMIT = 20;
+/**
+ * Generates a readable ES module from a program that has parsed without errors. A component is
+ * inlined where it is used, unless that adds more than INLINE_LIMIT lines compared to a function
+ * and its calls. The module is generated again with each such candidate as a function, and the one
+ * that saves the most goes first: that changes the sizes of the components inside it. A component
+ * of another module is a candidate too; its function is in that module, and counts as one copy.
+ * Then, if the code creates more than ELEMENT_HELPER_LIMIT elements, it is generated again with
+ * the helper that creates them.
+ */
+export declare function generateJs(program: ast.Program, options: JsOptions): string;

package/dist/codegen/js.js

@@ -0,0 +1,113 @@
+import { declarationsOf } from "./analysis.js";
+import { FunctionEmitter } from "./functions.js";
+import { startWorker } from "./go-helpers.js";
+import { HELPER_NEEDS, HELPERS } from "./helpers.js";
+/** A component whose inlined copies add more lines than this to its module becomes a function. */
+export const INLINE_LIMIT = 100;
+/**
+ * A module whose code creates more elements than this creates them with $$element, which takes
+ * their attributes: its definition takes less than the statements it saves.
+ */
+export const ELEMENT_HELPER_LIMIT = 20;
+/**
+ * Generates a readable ES module from a program that has parsed without errors. A component is
+ * inlined where it is used, unless that adds more than INLINE_LIMIT lines compared to a function
+ * and its calls. The module is generated again with each such candidate as a function, and the one
+ * that saves the most goes first: that changes the sizes of the components inside it. A component
+ * of another module is a candidate too; its function is in that module, and counts as one copy.
+ * Then, if the code creates more than ELEMENT_HELPER_LIMIT elements, it is generated again with
+ * the helper that creates them.
+ */
+export function generateJs(program, options) {
+    const { code, functions, elements } = chooseFunctions(program, options);
+    if (elements <= ELEMENT_HELPER_LIMIT)
+        return code;
+    return new JsGenerator(program, { ...options, functions, elementHelper: true }).generate();
+}
+/** The code with the components that become functions; see generateJs. */
+function chooseFunctions(program, options) {
+    const functions = new Set();
+    const generate = (names) => {
+        const generator = new JsGenerator(program, { ...options, functions: names });
+        const code = generator.generate();
+        const lines = code.split('\n').filter((line) => line.trim() !== '').length;
+        return { code, lines, generator };
+    };
+    let current = generate(functions);
+    while (true) {
+        let best = null;
+        const { inlined, alwaysInlined } = current.generator;
+        for (const [name, { copies, lines }] of inlined) {
+            // A function and its calls are larger than one copy, and save no more than the copies take.
+            if (copies < 2 || lines <= INLINE_LIMIT || alwaysInlined.has(name))
+                continue;
+            const trial = generate(new Set([...functions, name]));
+            const own = options.components?.has(name) ? Math.ceil(lines / copies) : 0;
+            const saved = current.lines - trial.lines - own;
+            if (saved > INLINE_LIMIT && (!best || saved > best.saved))
+                best = { ...trial, name, saved };
+        }
+        if (!best) {
+            return { code: current.code, functions, elements: current.generator.createdElements };
+        }
+        functions.add(best.name);
+        current = best;
+    }
+}
+/** The whole module: its statements, plus the helpers that its code needs. */
+class JsGenerator extends FunctionEmitter {
+    generate() {
+        this.withScope(declarationsOf(this.program.body), () => {
+            this.statements(this.program.body);
+            this.webComponentClasses();
+            this.hiddenExports();
+        });
+        const { goroutines } = this.options;
+        // The worker module runs the functions that `go` calls (see goroutines.ts).
+        if (goroutines && 'targets' in goroutines) {
+            const names = goroutines.targets.map((name) => this.name(name));
+            this.helpers.add('serve');
+            this.lines.push('', `const $$goroutines = { ${names.join(', ')} };`, '$$serve($$goroutines);');
+        }
+        // The CSS of the components goes before the code, so that the page has it before the markup.
+        const styles = this.styleRegistrations();
+        let lines = this.lines;
+        if (styles.length > 0)
+            this.helpers.add('style');
+        if (this.helpers.size > 0) {
+            const needed = new Set();
+            const add = (helper) => {
+                if (needed.has(helper))
+                    return;
+                needed.add(helper);
+                for (const other of HELPER_NEEDS[helper] ?? [])
+                    add(other);
+            };
+            for (const helper of this.helpers)
+                add(helper);
+            const workerUrl = goroutines && 'workerUrl' in goroutines ? goroutines.workerUrl : '';
+            const helpers = [...needed]
+                .sort()
+                .flatMap((helper, i) => [
+                ...(i > 0 ? [''] : []),
+                ...HELPERS[helper],
+                ...(helper === 'go' ? ['', ...startWorker(workerUrl)] : []),
+            ]);
+            let imports = 0;
+            while (lines[imports]?.startsWith('import '))
+                imports++;
+            const rest = lines.slice(imports);
+            while (rest[0] === '')
+                rest.shift();
+            lines = [
+                ...lines.slice(0, imports),
+                ...(imports > 0 ? [''] : []),
+                ...helpers,
+                ...(styles.length > 0 ? ['', ...styles] : []),
+                ...(rest.length > 0 ? [''] : []),
+                ...rest,
+            ];
+        }
+        return lines.length === 0 ? '' : `${lines.join('\n')}\n`;
+    }
+}

package/dist/codegen/mutations.d.ts

@@ -0,0 +1,10 @@
+import type * as ast from '../ast.ts';
+/** The variable at the start of `a.b[i].c()`, or `null`. */
+export declare function rootName(node: ast.Expression): string | null;
+/** Names whose values a node reads, not counting code that runs on events. */
+export declare function readNames(node: ast.Node, names: Set<string>): void;
+/**
+ * Names an effect reads while it runs: not in the functions it creates, which run later, nor in
+ * its `defer`, nor the variables it writes, or `count++` would run it again.
+ */
+export declare function effectReads(node: ast.Node, names: Set<string>): void;