rooklang 0.0.0-stage → 0.3.1

package/dist/codegen/updates.d.ts

@@ -0,0 +1,51 @@
+import type * as ast from '../ast.ts';
+import { type Type } from '../checker/types.ts';
+import type { Reactive, Source, Write } from './reactive.ts';
+import { StatementEmitter } from './statements.ts';
+/**
+ * Updates after changes of component state. Each state variable gets an update function; every
+ * place that changes the variable calls it. Those places are written before it is known what the
+ * update needs, so they get a marker that is replaced at the end of the component (see
+ * resolveMarkers): by the call, by the only update statement, or by nothing.
+ */
+export declare abstract class UpdateEmitter extends StatementEmitter {
+    /** The component whose code is being written, if it has state or reactive properties. */
+    protected reactive: Reactive | null;
+    /** Inside event handlers, which cannot run before the markup exists. */
+    protected inHandler: number;
+    /**
+     * Inside code that runs while live markup is created or updated: its expressions, the functions
+     * they call and the callbacks they pass (`items.map(item => ...)`). Changes there do not update
+     * the markup, which would update it again; code that runs later (handlers) is not included.
+     */
+    protected rendering: number;
+    /** After a statement that changes state, the update of what depends on it. */
+    protected statement(node: ast.Statement): void;
+    protected changesState(body: ast.Expression): boolean;
+    protected withRendering<T>(rendering: number, emit: () => T): T;
+    /** Records a place that changes a source and returns its marker; see resolveMarkers. */
+    protected write(source: Source, skip?: number | null): string;
+    /** The type from the checker; literal types count as their base types here (`"all"` → string). */
+    protected typeOf(node: ast.Expression): Type | undefined;
+    /** State that a statement changes, when it runs after the component's markup is created. */
+    private changedBy;
+    private updates;
+    /** Marker statements for the start of a branch, at `position` in the source. */
+    private markers;
+    /** `() => value`, evaluated by a helper when the markup is created and on updates. */
+    protected liveFunction(node: ast.Expression): string;
+    /**
+     * An expression that is evaluated again on updates: elements inside it are created in place,
+     * so that each evaluation creates new ones.
+     */
+    protected liveExpression(node: ast.Expression, precedence?: number): string;
+}
+/**
+ * Replaces the markers of a component's sources: by the call of the update function, by the only
+ * update statement, or by nothing when no markup depends on the source.
+ */
+export declare function resolveMarkers(block: string, reactive: Reactive): string;
+/** The update statements that a place changing the source needs, the computations first. */
+export declare function needed(source: Source, write: Write): string[];
+/** One place changes the source, after the markup exists, and needs one update statement. */
+export declare function inlinesUpdate(source: Source): boolean;

package/dist/codegen/updates.js

@@ -0,0 +1,201 @@
+import { widenLiterals } from "../checker/types.js";
+import { StatementEmitter } from "./statements.js";
+import { startsWithObjectLiteral } from "./analysis.js";
+import { ARROW } from "./syntax.js";
+/**
+ * Updates after changes of component state. Each state variable gets an update function; every
+ * place that changes the variable calls it. Those places are written before it is known what the
+ * update needs, so they get a marker that is replaced at the end of the component (see
+ * resolveMarkers): by the call, by the only update statement, or by nothing.
+ */
+export class UpdateEmitter extends StatementEmitter {
+    /** The component whose code is being written, if it has state or reactive properties. */
+    reactive = null;
+    /** Inside event handlers, which cannot run before the markup exists. */
+    inHandler = 0;
+    /**
+     * Inside code that runs while live markup is created or updated: its expressions, the functions
+     * they call and the callbacks they pass (`items.map(item => ...)`). Changes there do not update
+     * the markup, which would update it again; code that runs later (handlers) is not included.
+     */
+    rendering = 0;
+    /** After a statement that changes state, the update of what depends on it. */
+    statement(node) {
+        const { reactive } = this;
+        if (reactive && this.fn === reactive.setup && reactive.declaresRenderFunction(node)) {
+            this.withRendering(this.rendering + 1, () => super.statement(node));
+            return;
+        }
+        // The body itself runs before the markup exists, but the derived values it changes stay right.
+        if (reactive && this.fn === reactive.setup && this.rendering === 0) {
+            const changed = reactive.writtenBy(node, (expression) => this.typeOf(expression));
+            super.statement(node);
+            for (const source of changed) {
+                for (const computation of source.computations)
+                    this.line(computation);
+            }
+            return;
+        }
+        const written = this.changedBy(node);
+        if (written.length === 0) {
+            super.statement(node);
+            return;
+        }
+        switch (node.kind) {
+            case 'ReturnStatement':
+            case 'ThrowStatement': {
+                // The update goes between computing the value and leaving the function.
+                const values = node.kind === 'ThrowStatement' ? [node.argument] : node.values;
+                const temp = this.temp();
+                this.withHoisting(true, () => {
+                    const rendered = values.map((value) => this.expression(value, ARROW));
+                    const value = rendered.length === 1 ? rendered[0] : `[${rendered.join(', ')}]`;
+                    this.line(`const ${temp} = ${value};`);
+                });
+                this.updates(written);
+                this.line(`${node.kind === 'ThrowStatement' ? 'throw' : 'return'} ${temp};`);
+                return;
+            }
+            case 'IfStatement':
+            case 'ForStatement':
+            case 'ForInStatement':
+            case 'SwitchStatement':
+                // The change is in a condition: update at the start of every branch, before anything in
+                // it can leave the function, and after the statement.
+                super.statement(withFirst(node, (position) => this.markers(written, position)));
+                this.updates(written);
+                return;
+            default:
+                super.statement(node);
+                this.updates(written);
+        }
+    }
+    changesState(body) {
+        return this.changedBy(body).length > 0;
+    }
+    withRendering(rendering, emit) {
+        const saved = this.rendering;
+        this.rendering = rendering;
+        try {
+            return emit();
+        }
+        finally {
+            this.rendering = saved;
+        }
+    }
+    /** Records a place that changes a source and returns its marker; see resolveMarkers. */
+    write(source, skip = null) {
+        source.writes.push({ early: this.inHandler === 0, skip });
+        return `\uE000${source.id}${skip === null ? '' : `:${skip}`}\uE001`;
+    }
+    /** The type from the checker; literal types count as their base types here (`"all"` → string). */
+    typeOf(node) {
+        const type = this.options.types?.get(node);
+        return type && widenLiterals(type);
+    }
+    /** State that a statement changes, when it runs after the component's markup is created. */
+    changedBy(node) {
+        const { reactive } = this;
+        if (!reactive || this.fn === reactive.setup || this.rendering > 0)
+            return [];
+        return [...reactive.writtenBy(node, (expression) => this.typeOf(expression))];
+    }
+    updates(sources) {
+        for (const source of sources)
+            this.line(`${this.write(source)};`);
+    }
+    /** Marker statements for the start of a branch, at `position` in the source. */
+    markers(sources, position) {
+        return sources.map((source) => {
+            const expression = {
+                kind: 'Identifier',
+                name: this.write(source),
+                start: position,
+                end: position,
+            };
+            return { kind: 'ExpressionStatement', expression, start: position, end: position };
+        });
+    }
+    /** `() => value`, evaluated by a helper when the markup is created and on updates. */
+    liveFunction(node) {
+        const text = this.liveExpression(node);
+        return `() => ${startsWithObjectLiteral(node) ? `(${text})` : text}`;
+    }
+    /**
+     * An expression that is evaluated again on updates: elements inside it are created in place,
+     * so that each evaluation creates new ones.
+     */
+    liveExpression(node, precedence = ARROW) {
+        return this.withRendering(this.rendering + 1, () => this.withHoisting(false, () => this.expression(node, precedence)));
+    }
+}
+/**
+ * Replaces the markers of a component's sources: by the call of the update function, by the only
+ * update statement, or by nothing when no markup depends on the source.
+ */
+export function resolveMarkers(block, reactive) {
+    const sources = new Map();
+    for (const source of reactive.sources.values())
+        sources.set(source.id, source);
+    return block.replace(/^([ \t]*)\uE000(\d+)(?::(\d+))?\uE001;\n/gm, (line, indent, id, skip) => {
+        const source = sources.get(Number(id));
+        if (!source)
+            return line;
+        const dependents = needed(source, { early: false, skip: skip ? Number(skip) : null });
+        if (dependents.length === 0)
+            return '';
+        const text = inlinesUpdate(source) ? dependents[0] : `${source.update}();`;
+        return `${indent}${text}\n`;
+    });
+}
+/** The update statements that a place changing the source needs, the computations first. */
+export function needed(source, write) {
+    return [...source.computations, ...source.dependents.filter((_, i) => i !== write.skip)];
+}
+/** One place changes the source, after the markup exists, and needs one update statement. */
+export function inlinesUpdate(source) {
+    const [write] = source.writes;
+    if (source.writes.length !== 1 || write.early)
+        return false;
+    const dependents = needed(source, write);
+    return dependents.length === 1 && !dependents[0].includes('\n');
+}
+/**
+ * A copy of an if/for/switch statement with statements added at the start of every branch or
+ * loop body; `first` gets the position where they go.
+ */
+function withFirst(node, first) {
+    const prepend = (body, end) => [
+        ...first(body[0]?.start ?? end),
+        ...body,
+    ];
+    const block = (node) => ({
+        ...node,
+        body: prepend(node.body, node.end - 1),
+    });
+    switch (node.kind) {
+        case 'IfStatement': {
+            const { alternate } = node;
+            return {
+                ...node,
+                consequent: block(node.consequent),
+                alternate: alternate === null
+                    ? null
+                    : alternate.kind === 'IfStatement'
+                        ? withFirst(alternate, first)
+                        : block(alternate),
+            };
+        }
+        case 'ForStatement':
+        case 'ForInStatement':
+            return { ...node, body: block(node.body) };
+        case 'SwitchStatement':
+            return {
+                ...node,
+                cases: node.cases.map((switchCase) => ({
+                    ...switchCase,
+                    body: prepend(switchCase.body, switchCase.end),
+                })),
+            };
+    }
+}

package/dist/codegen/web-components.d.ts

@@ -0,0 +1,20 @@
+import type * as ast from '../ast.ts';
+import { ComponentEmitter } from './components.ts';
+/**
+ * Web components: `@html-tag comp Card(count number) { ... }` is a function component, and also the
+ * class of a custom element `<card>`, defined at the end of the module, when the names it uses
+ * have their values.
+ *
+ * The element renders the component into its shadow root when it is connected. When it is
+ * disconnected and not put back in the same task, the component is removed: the functions
+ * returned by `mount()` run. Moving the element keeps its markup.
+ *
+ * Every property except `children` is a JS property of the element; its setter updates the markup.
+ * Strings, numbers and bools also have attributes: `item-count="3"` sets `itemCount` to 3, and a
+ * bool attribute sets true by its presence. A removed attribute leaves the default value.
+ * `children` is a `<slot>`: what is inside the element is shown there.
+ */
+export declare abstract class WebComponentEmitter extends ComponentEmitter {
+    protected webComponentClasses(): void;
+    protected webComponentClass(component: ast.ComponentDeclaration): void;
+}

package/dist/codegen/web-components.js

@@ -0,0 +1,149 @@
+import { attributeKind, attributeName, htmlTagName } from "../html-tag.js";
+import { ComponentEmitter } from "./components.js";
+/**
+ * Web components: `@html-tag comp Card(count number) { ... }` is a function component, and also the
+ * class of a custom element `<card>`, defined at the end of the module, when the names it uses
+ * have their values.
+ *
+ * The element renders the component into its shadow root when it is connected. When it is
+ * disconnected and not put back in the same task, the component is removed: the functions
+ * returned by `mount()` run. Moving the element keeps its markup.
+ *
+ * Every property except `children` is a JS property of the element; its setter updates the markup.
+ * Strings, numbers and bools also have attributes: `item-count="3"` sets `itemCount` to 3, and a
+ * bool attribute sets true by its presence. A removed attribute leaves the default value.
+ * `children` is a `<slot>`: what is inside the element is shown there.
+ */
+export class WebComponentEmitter extends ComponentEmitter {
+    webComponentClasses() {
+        for (const component of this.components.values()) {
+            if (component.htmlTag)
+                this.webComponentClass(component);
+        }
+    }
+    webComponentClass(component) {
+        this.helpers.add('owner');
+        const name = component.name.name;
+        const className = `$$${name}Element`;
+        const props = component.params.filter((param) => param.name.name !== 'children');
+        const kinds = props.map((param) => attributeKind(param.type, this.typeAliases));
+        const observed = props
+            .filter((_, i) => kinds[i] !== null)
+            .map((param) => JSON.stringify(attributeName(param.name.name)));
+        // A missing property: undefined gives the default value, others get their zero value.
+        const value = (param) => param.defaultValue
+            ? `values.${param.name.name}`
+            : `values.${param.name.name} ?? ${(param.type && this.zeroValue(param.type)) ?? 'undefined'}`;
+        // The properties come from `#args()`, in the order of the setter; `children` is a slot.
+        const slot = component.params.findIndex((param) => param.name.name === 'children');
+        let prepare = null;
+        const args = props.length > 0 ? ['...this.#args()'] : [];
+        if (slot === props.length) {
+            args.push('document.createElement("slot")');
+        }
+        else if (slot >= 0) {
+            prepare = `args.splice(${slot}, 0, document.createElement("slot"));`;
+            args[0] = '...args';
+        }
+        const names = props.map((param) => JSON.stringify(param.name.name)).join(', ');
+        const body = this.capture(() => {
+            if (observed.length > 0)
+                this.line(`static observedAttributes = [${observed.join(', ')}];`);
+            this.line('#values = {};');
+            this.line('#update = null;');
+            this.line('#remove = null;');
+            this.lines.push('');
+            this.line('constructor() {');
+            this.line('  super();');
+            this.line('  this.attachShadow({ mode: "open" });');
+            if (props.length > 0) {
+                // A property set before the class was defined hides its setter.
+                this.line(`  for (const name of [${names}]) {`);
+                this.line('    if (!Object.hasOwn(this, name)) continue;');
+                this.line('    const value = this[name];');
+                this.line('    delete this[name];');
+                this.line('    this[name] = value;');
+                this.line('  }');
+            }
+            this.line('}');
+            this.lines.push('');
+            this.line('connectedCallback() {');
+            this.line('  if (this.#remove) return;');
+            if (prepare) {
+                this.line('  const args = this.#args();');
+                this.line(`  ${prepare}`);
+            }
+            this.line(`  const [[node, update], remove] = $$owned(() => $$${name}(${args.join(', ')}));`);
+            this.line('  this.#update = update ?? null;');
+            this.line('  this.#remove = remove;');
+            // The styles of the page do not reach a shadow root: it gets the CSS of the module.
+            if (this.usedStyles.size > 0) {
+                this.line('  const style = document.createElement("style");');
+                this.line('  style.textContent = $$styles.join("\\n");');
+                this.line('  this.shadowRoot.append(style, node);');
+            }
+            else {
+                this.line('  this.shadowRoot.append(node);');
+            }
+            this.line('}');
+            this.lines.push('');
+            this.line('disconnectedCallback() {');
+            this.line('  queueMicrotask(() => {');
+            this.line('    if (this.isConnected || !this.#remove) return;');
+            this.line('    this.#remove();');
+            this.line('    this.#update = this.#remove = null;');
+            this.line('    this.shadowRoot.replaceChildren();');
+            this.line('  });');
+            this.line('}');
+            if (observed.length > 0) {
+                this.lines.push('');
+                this.line('attributeChangedCallback(name, old, value) {');
+                this.line('  switch (name) {');
+                props.forEach((param, i) => {
+                    const kind = kinds[i];
+                    if (!kind)
+                        return;
+                    const converted = kind === 'string'
+                        ? 'value ?? undefined'
+                        : kind === 'number'
+                            ? 'value === null ? undefined : Number(value)'
+                            : 'value === null ? undefined : true';
+                    this.line(`    case ${JSON.stringify(attributeName(param.name.name))}:`);
+                    this.line(`      this.${param.name.name} = ${converted};`);
+                    this.line('      break;');
+                });
+                this.line('  }');
+                this.line('}');
+            }
+            for (const param of props) {
+                const prop = param.name.name;
+                this.lines.push('');
+                this.line(`get ${prop}() {`);
+                this.line(`  return this.#values.${prop};`);
+                this.line('}');
+                this.lines.push('');
+                this.line(`set ${prop}(value) {`);
+                this.line(`  this.#values.${prop} = value;`);
+                this.line('  this.#update?.(...this.#args());');
+                this.line('}');
+            }
+            if (props.length > 0) {
+                this.lines.push('');
+                this.line('#args() {');
+                this.line('  const values = this.#values;');
+                this.line('  return [');
+                for (const param of props)
+                    this.line(`    ${value(param)},`);
+                this.line('  ];');
+                this.line('}');
+            }
+        });
+        this.blankLine();
+        this.line(`class ${className} extends HTMLElement {`);
+        this.lines.push(...body);
+        this.line('}');
+        this.lines.push('');
+        const tag = JSON.stringify(htmlTagName(component));
+        this.line(`customElements.define(${tag}, ${className});`);
+    }
+}

package/dist/compile-file.d.ts

@@ -0,0 +1,11 @@
+import type { CompileResult } from './compile.ts';
+/** Compile errors, already formatted for the terminal. */
+export declare class CompileError extends Error {
+}
+/** Compiles a file; prints its warnings unless `quiet`, throws a CompileError on errors. */
+export declare function compileFile(path: string, options: {
+    rewriteImports: boolean;
+    typeCheck: boolean;
+    markup?: boolean;
+    quiet?: boolean;
+}): CompileResult;

package/dist/compile-file.js

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { formatDiagnostic } from "./diagnostics.js";
+import { compile } from "./index.js";
+import { SourceFile } from "./source.js";
+// Compiling a file for the CLI: errors become one exception with the messages for the terminal.
+/** Compile errors, already formatted for the terminal. */
+export class CompileError extends Error {
+}
+/** Compiles a file; prints its warnings unless `quiet`, throws a CompileError on errors. */
+export function compileFile(path, options) {
+    const source = readFileSync(path, 'utf8');
+    const { quiet, ...compileOptions } = options;
+    const result = compile(source, { filename: path, ...compileOptions });
+    const file = new SourceFile(path, source);
+    if (!quiet) {
+        for (const warning of result.warnings) {
+            console.warn(`${formatDiagnostic(file, warning, 'warning')}\n`);
+        }
+    }
+    if (result.diagnostics.length > 0) {
+        throw new CompileError(result.diagnostics.map((d) => formatDiagnostic(file, d)).join('\n\n'));
+    }
+    return result;
+}

package/dist/compile.d.ts

@@ -0,0 +1,53 @@
+import type * as ast from './ast.ts';
+import { type CheckOptions, type ImportResult, type Library } from './checker/checker.ts';
+import type { Diagnostic } from './diagnostics.ts';
+import { type StyleModule } from './style-modules.ts';
+export interface CoreCompileOptions {
+    /** Replace `.rk` with `.js` in relative import paths. Defaults to `true`. */
+    rewriteImports?: boolean;
+    /** Check types before generating code. Defaults to `true`. */
+    typeCheck?: boolean;
+    /** Markup and components; read unless false (the entries decide it, see src/config.ts). */
+    markup?: boolean;
+    /** The exports of an imported `.rk` module; without it, imports are untyped (`any`). */
+    importModule?: ((specifier: string) => ImportResult) | undefined;
+    /** The exports of other imports, from TypeScript declarations; without it, they are untyped. */
+    importDeclarations?: ((specifier: string) => ImportResult) | undefined;
+    /** Types of the standard library and the DOM beyond the built-in ones. */
+    library?: Library | undefined;
+    /** Also write a TypeScript declaration file; needs type checking. */
+    declarations?: boolean;
+    /** The text of an imported CSS module, `./button.module.css`, or null if it cannot be read. */
+    readStyleModule?: ((specifier: string) => string | null) | undefined;
+    /** Where the worker module of `go` is, relative to the module; see workerUrl(). */
+    workerUrl?: string | undefined;
+}
+/**
+ * Where the worker module of a module is: a `.worker.js` next to its `.js`, or, where `.rk`
+ * files are imported as they are (`rook run`), the module itself with `?goroutines`. Vite drops
+ * the query of a worker's URL, so its plugin gives another path (vite.ts).
+ */
+export declare function workerUrl(file: string, rewriteImports: boolean): string;
+export interface CompileResult {
+    /** The generated ES module; empty when there are diagnostics. */
+    code: string;
+    diagnostics: Diagnostic[];
+    /** Problems that do not stop compilation, sorted by position. */
+    warnings: Diagnostic[];
+    /** Relative paths of the `.rk` modules and CSS modules this file imports, as written. */
+    dependencies: string[];
+    /** The `.d.ts` for the module, with the `declarations` option. */
+    declarations?: string;
+    /** The worker module that runs the functions `go` calls, when the module has `go`. */
+    worker?: string;
+}
+export declare function compileModule(source: string, options?: CoreCompileOptions): CompileResult;
+/**
+ * The options of the checker for a program: its imports, with the CSS modules it imports, which
+ * are read and parsed here (or what is wrong with them), and the library.
+ */
+export declare function prepareCheck(program: ast.Program, options: CoreCompileOptions): {
+    styleModules: Map<string, StyleModule>;
+    problems: Diagnostic[];
+    checkOptions: CheckOptions;
+};