rooklang 0.3.1 → 0.3.3

package/README.md

@@ -3,7 +3,8 @@
 **English** · [Русский](README.ru.md)
 
 A language with the semantics of JavaScript, Go-style syntax, goroutines on real threads and static
-types. It compiles to readable JavaScript without a runtime (WebAssembly is planned).
+types. It compiles to readable JavaScript with a small runtime library for channels, goroutines
+and markup (WebAssembly is planned).
 
 ```go
 async func square(jobs <-chan number, results chan<- number) {
@@ -55,12 +56,15 @@ Specification: [docs/spec.md](docs/spec.md), design of components:
 Rook needs Node.js ≥ 24.
 
 ```sh
-npm install --save-dev rooklang
+npm install rooklang
 npx rook build app.rk                # app.js next to the source
 npx rook build src --out-dir dist       # every module of a folder
 npx rook run app.rk                  # compile and run
 ```
 
+The compiled code imports what channels, goroutines and markup need from `rooklang/runtime`, so
+the package is a dependency of the project, not only of its build.
+
 From code, the compiler is `import { compile } from 'rooklang'`. The package also has the
 [Vite](#vite) plugin, `rooklang/vite`, and `rooklang/browser`, the compiler without the
 TypeScript compiler for running in a browser, as in the site's playground: there imports are not
@@ -90,6 +94,7 @@ staged version is formatted, so edits that are not staged stay out of the commit
 | `npm run check`                   | All at once: types, lint, format, tests                 |
 | `npm run build`                   | Build the npm package to `dist/`                        |
 | `npm run vscode:install`          | Build and install the VS Code extension                 |
+| `npm run vscode:package`          | Pack the VS Code extension into `rooklang.vsix`         |
 
 Options of `build`: `--out-dir dir` writes the `.js` files to a separate folder, `--stdout` prints
 the JS of one file, `--no-check` skips type checking. `--markup` and `--no-markup` turn markup and
@@ -108,8 +113,16 @@ version yet, runs `npm run check`, builds `dist/`, publishes the package to npm
 
 [editors/vscode/](editors/vscode/) has an extension for `.rk` files: highlighting of code, types
 and markup, errors as you type and completion of names, members, types, tags and attributes, from a
-language server with the compiler. `npm run vscode:install` builds it and installs it with `code`;
-see [editors/vscode/README.md](editors/vscode/README.md).
+language server with the compiler. It is "Rook Language" in the
+[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Qwern9876r.rooklang) and on [Open VSX](https://open-vsx.org/extension/Qwern9876r/rooklang).
+`npm run vscode:install` builds it from the source and installs it with `code`; how to work on it
+is in [editors/vscode/DEVELOPMENT.md](editors/vscode/DEVELOPMENT.md).
+
+A release of the extension is a new `version` in `editors/vscode/package.json` on `main`: the
+workflow [.github/workflows/vscode.yml](.github/workflows/vscode.yml) sees that a store does not
+have this version yet, runs `npm run check`, publishes the extension to the Marketplace and Open VSX
+and tags the commit `vscode-v0.1.1`. The setup of the stores is in
+[editors/vscode/DEVELOPMENT.md](editors/vscode/DEVELOPMENT.md#publishing).
 
 ## Documentation site
 

package/README.ru.md

@@ -3,7 +3,8 @@
 [English](README.md) · **Русский**
 
 Язык с семантикой JavaScript, синтаксисом в духе Go, горутинами на настоящих потоках и статической
-типизацией. Компилируется в читаемый JavaScript без рантайма (в планах — WebAssembly).
+типизацией. Компилируется в читаемый JavaScript с маленькой библиотекой рантайма для каналов,
+горутин и разметки (в планах — WebAssembly).
 
 ```go
 async func square(jobs <-chan number, results chan<- number) {
@@ -55,12 +56,15 @@ for let i = 0; i < 4; i++ {
 Нужен Node.js ≥ 24.
 
 ```sh
-npm install --save-dev rooklang
+npm install rooklang
 npx rook build app.rk                # app.js рядом с исходником
 npx rook build src --out-dir dist       # все модули папки
 npx rook run app.rk                  # скомпилировать и запустить
 ```
 
+Скомпилированный код импортирует то, что нужно каналам, горутинам и разметке, из
+`rooklang/runtime`, поэтому пакет — зависимость проекта, а не только его сборки.
+
 Из кода компилятор подключается как `import { compile } from 'rooklang'`. Ещё в пакете есть
 плагин для [Vite](#vite) — `rooklang/vite` — и `rooklang/browser`: компилятор без
 компилятора TypeScript, для работы в браузере, как в песочнице сайта; импорты там не проверяются
@@ -91,6 +95,7 @@ Node.js ≥ 24 (`nvm use`). Компилятор написан на TypeScript,
 | `npm run check`                   | Всё сразу — типы, линт, формат, тесты                    |
 | `npm run build`                   | Собрать npm-пакет в `dist/`                              |
 | `npm run vscode:install`          | Собрать и установить расширение для VS Code              |
+| `npm run vscode:package`          | Упаковать расширение для VS Code в `rooklang.vsix`       |
 
 Опции `build`: `--out-dir dir` — писать `.js` в отдельную папку, `--stdout` — вывести JS одного
 файла в консоль, `--no-check` — без проверки типов. `--markup` и `--no-markup` включают или
@@ -109,8 +114,16 @@ Node.js ≥ 24 (`nvm use`). Компилятор написан на TypeScript,
 
 В [editors/vscode/](editors/vscode/) лежит расширение для файлов `.rk`: подсветка кода, типов и
 разметки, ошибки прямо при наборе и автодополнение имён, членов, типов, тегов и атрибутов — от
-языкового сервера с компилятором. `npm run vscode:install` собирает его и устанавливает через
-`code`; подробности — в [editors/vscode/README.ru.md](editors/vscode/README.ru.md).
+языкового сервера с компилятором. Оно называется «Rook Language» и есть в
+[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=Qwern9876r.rooklang) и в [Open VSX](https://open-vsx.org/extension/Qwern9876r/rooklang).
+`npm run vscode:install` собирает его из исходников и устанавливает через `code`; как с ним
+работать — в [editors/vscode/DEVELOPMENT.ru.md](editors/vscode/DEVELOPMENT.ru.md).
+
+Релиз расширения — это новая `version` в `editors/vscode/package.json` в `main`: workflow
+[.github/workflows/vscode.yml](.github/workflows/vscode.yml) видит, что в магазине такой версии ещё
+нет, запускает `npm run check`, публикует расширение в Marketplace и Open VSX и ставит на коммит тег
+`vscode-v0.1.1`. Как настроены магазины — в
+[editors/vscode/DEVELOPMENT.ru.md](editors/vscode/DEVELOPMENT.ru.md#публикация).
 
 ## Сайт с документацией
 

package/dist/ast/expressions.d.ts

@@ -1,7 +1,7 @@
 import type { NodeBase, Parameter } from './declarations.ts';
 import type { ElementExpression, TypeNode } from './markup.ts';
 import type { BlockStatement } from './statements.ts';
-export type Expression = Identifier | NumberLiteral | BigIntLiteral | StringLiteral | TemplateLiteral | BooleanLiteral | NullLiteral | ThisExpression | SuperExpression | ArrayLiteral | ObjectLiteral | FuncExpression | ArrowFunction | UnaryExpression | BinaryExpression | ConditionalExpression | CallExpression | NewExpression | MemberExpression | IndexExpression | ElementExpression | DecoratorMember | DecoratorGet | AsExpression | GoExpression | ChanExpression | ConversionExpression | MakeExpression;
+export type Expression = Identifier | NumberLiteral | BigIntLiteral | StringLiteral | TemplateLiteral | BooleanLiteral | NullLiteral | ThisExpression | SuperExpression | ArrayLiteral | ObjectLiteral | FuncExpression | ArrowFunction | UnaryExpression | BinaryExpression | ConditionalExpression | CallExpression | NewExpression | MemberExpression | IndexExpression | ElementExpression | DecoratorMember | DecoratorGet | AsExpression | GoExpression | ChanExpression | StreamChanExpression | QueueExpression | ConversionExpression | MakeExpression;
 /**
  * `[]byte("rook")`: the UTF-8 bytes of a string. `string(data)`, the way back, is a call, since
  * `string` may be the name of a value.
@@ -27,6 +27,21 @@ export interface ChanExpression extends NodeBase {
     element: TypeNode;
     size: Expression | null;
 }
+/** `queue<number>()`: a new, empty queue; `queue<number>([1, 2])` starts with these values. */
+export interface QueueExpression extends NodeBase {
+    kind: 'QueueExpression';
+    element: TypeNode;
+    items: Expression | null;
+}
+/**
+ * `chan(res.body, 4)`: a channel that receives the chunks of a ReadableStream, with room for 4,
+ * and a channel that gets the error of the stream, or null at its end.
+ */
+export interface StreamChanExpression extends NodeBase {
+    kind: 'StreamChanExpression';
+    stream: Expression;
+    size: Expression | null;
+}
 /**
  * `go work(x)`: calls a function of the module in a worker, with copies of the arguments. As an
  * expression it is a Promise of what the function returns; as a statement nothing waits for it.

package/dist/ast/markup.d.ts

@@ -60,7 +60,7 @@ export interface EventHandler extends NodeBase {
     kind: 'EventHandler';
     body: SimpleStatement[];
 }
-export type TypeNode = TypeReference | ArrayType | NullableType | FuncType | ComponentType | ObjectType | UnionType | LiteralType | ChanType;
+export type TypeNode = TypeReference | ArrayType | NullableType | FuncType | ComponentType | ObjectType | UnionType | LiteralType | ChanType | QueueType;
 /**
  * `chan number`: a channel of numbers, made by `chan<number>(size)`; `chan<- number` only sends
  * and `<-chan number` only receives.
@@ -70,6 +70,11 @@ export interface ChanType extends NodeBase {
     element: TypeNode;
     direction: 'both' | 'send' | 'receive';
 }
+/** `queue number`: a queue of numbers, made by `queue<number>()`. */
+export interface QueueType extends NodeBase {
+    kind: 'QueueType';
+    element: TypeNode;
+}
 /** A named type: `number`, `User`, `Point`, `Box<number>`. */
 export interface TypeReference extends NodeBase {
     kind: 'TypeReference';

package/dist/browser.d.ts

@@ -23,6 +23,11 @@ export interface BrowserCompileResult {
 export interface BrowserOptions {
     /** Markup and components; off by default, as in a package without them. */
     markup?: boolean;
+    /**
+     * Import the runtime from "rooklang/runtime", the default, or put it into the module: code that
+     * runs without imports, as in the playground, needs it there.
+     */
+    runtime?: 'import' | 'inline';
 }
 /** Compiles a program; `workerUrl` is where its worker module of `go` will be, if not next to it. */
 export declare function compile(source: string, workerUrl?: string | null, options?: BrowserOptions): BrowserCompileResult;

package/dist/browser.js

@@ -12,6 +12,7 @@ export function compile(source, workerUrl, options = {}) {
         rewriteImports: false,
         workerUrl: workerUrl ?? undefined,
         markup: options.markup ?? false,
+        runtime: options.runtime,
     });
     const file = new SourceFile('', source);
     const located = (diagnostic) => {

package/dist/checker/assignments.d.ts

@@ -11,4 +11,9 @@ export declare abstract class AssignmentChecker extends InitializerChecker {
     /** The type a value assigned to `target` must have. */
     protected checkTarget(target: ast.Expression): Type;
     protected checkReturn(node: ast.ReturnStatement): void;
+    /**
+     * `return null, err` in a function of `(User, error)`: null takes the place of a value only
+     * together with an error that is not null. Returns whether the null is checked here.
+     */
+    private nullWithError;
 }

package/dist/checker/assignments.js

@@ -1,6 +1,7 @@
+import { guardedByError, unpackedResults } from "./error-results.js";
 import { isUntyped, countValues, callName, isCall } from "./helpers.js";
 import { InitializerChecker } from "./initializers.js";
-import { BOOL, ANY, isAssignable, isNullable, nonNull, typeToString, UNKNOWN, } from "./types.js";
+import { BOOL, ANY, isAssignable, isNullable, nonNull, nullable, typeToString, UNKNOWN, } from "./types.js";
 // Where values go: assignments to variables, fields and elements, and `return`. Both unpack a call
 // that returns several values.
 export class AssignmentChecker extends InitializerChecker {
@@ -26,12 +27,15 @@ export class AssignmentChecker extends InitializerChecker {
             this.error(`${prefix} ${callName(value)} returns ${countValues(returned)}`, value);
             return Array(count).fill(UNKNOWN);
         }
+        // `return f()` passes the results on as they are; variables get the values before an error
+        // as nullable (error-results.ts).
+        const types = context === 'return' ? type.types : unpackedResults(type.types);
         if (declared) {
-            for (const element of type.types)
+            for (const element of types)
                 this.expectAssignable(element, declared, value);
-            return type.types.map(() => declared);
+            return types.map(() => declared);
         }
-        return type.types;
+        return types;
     }
     checkAssignment(node) {
         const { targets, values, operator } = node;
@@ -187,11 +191,33 @@ export class AssignmentChecker extends InitializerChecker {
         if (values.length !== expected.length) {
             this.error(`wrong number of return values: expected ${expected.length}, got ${values.length}`, node);
         }
-        values.forEach((value, i) => {
+        const types = values.map((value, i) => this.checkValue(value, expected[i] ?? null));
+        types.forEach((type, i) => {
             const target = expected[i];
-            const type = this.checkValue(value, target ?? null);
-            if (target)
-                this.expectAssignable(type, target, value, ' in return');
+            if (!target)
+                return;
+            if (type.kind === 'null' && this.nullWithError(expected, types, values, i))
+                return;
+            this.expectAssignable(type, target, values[i], ' in return');
         });
     }
+    /**
+     * `return null, err` in a function of `(User, error)`: null takes the place of a value only
+     * together with an error that is not null. Returns whether the null is checked here.
+     */
+    nullWithError(expected, types, values, i) {
+        const last = expected.length - 1;
+        if (!guardedByError(expected).includes(i) || types.length !== expected.length)
+            return false;
+        const error = types[last];
+        const target = typeToString(expected[i]);
+        if (error.kind === 'null') {
+            this.error(`cannot return null with no error: make the result ${typeToString(nullable(expected[i]))} if the value may be null without an error`, values[i]);
+        }
+        else if (isNullable(error)) {
+            const name = values[last].kind === 'Identifier' ? values[last].name : 'err';
+            this.error(`null in place of ${target} needs an error that is not null: check it first, e.g. if ${name} != null { return null, ${name} }`, values[i]);
+        }
+        return true;
+    }
 }

package/dist/checker/base.d.ts

@@ -18,6 +18,8 @@ export declare abstract class CheckerBase {
     protected abstract checkTry(node: ast.TryStatement): void;
     protected abstract forget(target: ast.Expression): void;
     protected abstract narrowableBinding(node: ast.Expression): Binding | undefined;
+    /** The error for a value that may be null where it must not be. */
+    protected abstract nullError(node: ast.Expression): void;
     protected abstract checkFunction(params: readonly ast.Parameter[], type: FunctionType, results: Type[] | null, body: ast.BlockStatement | ast.Expression, options?: {
         isConstructor?: boolean;
         isComponent?: boolean;
@@ -94,7 +96,6 @@ export declare abstract class CheckerBase {
     constructor(program: ast.Program, options: CheckOptions);
     protected error(message: string, node: ast.NodeBase): void;
     protected expectAssignable(source: Type, target: Type, node: ast.NodeBase, context?: string): void;
-    protected nullError(node: ast.Expression): void;
     protected withScope<T>(check: () => T): T;
     protected withClass<T>(context: ClassContext | null, check: () => T): T;
     protected lookupValue(name: string): Binding | undefined;

package/dist/checker/base.js

@@ -7,10 +7,10 @@ import { explainMismatch, isAssignable, LazyMap, memberNames, nonNull, property,
 // declarations → classes → resolution → initializers → assignments → statements → control flow →
 // functions → expressions → operators → markup → forwarding → components → component values →
 // refs → styles → decorator wrappers → decorator exports → decorators → decorator members →
-// members → calls → goroutines → channels → bytes → loops → go for → iterators → completion →
-// Checker (checker.ts). Statements, expressions and markup check each other recursively, so
-// methods of later layers that earlier ones call are declared here as abstract. This layer has the
-// state of a check, diagnostics, scopes and names, and the DOM types.
+// members → calls → goroutines → channels → queues → bytes → loops → go for → iterators →
+// completion → Checker (checker.ts). Statements, expressions and markup check each other
+// recursively, so methods of later layers that earlier ones call are declared here as abstract.
+// This layer has the state of a check, diagnostics, scopes and names, and the DOM types.
 export class CheckerBase {
     program;
     options;
@@ -66,12 +66,6 @@ export class CheckerBase {
         }
         this.error(message, node);
     }
-    nullError(node) {
-        const name = node.kind === 'Identifier' ? node.name : null;
-        this.error(name !== null
-            ? `"${name}" may be null: check it with "if ${name} != null" or use "?."`
-            : 'this value may be null: check it for null or use "?."', node);
-    }
     withScope(check) {
         const saved = this.scope;
         this.scope = new Scope(saved);

package/dist/checker/builtins.js

@@ -5,6 +5,7 @@ import { SVG_TYPES } from "./dom-svg.js";
 import { chanOf } from "./channel.js";
 import { PROMISE } from "./promise.js";
 import { BUFFERS } from "./transfer.js";
+import { UNTYPED_GLOBALS } from "./untyped-globals.js";
 import { ANY, arrayOf, BIGINT, BOOL, ERROR, ERROR_CLASS, func, method, NUMBER, nullable, property, STRING, } from "./types.js";
 // Types of the JS standard library that Rook programs use most. Anything not listed here
 // can still be reached through the untyped globals below.
@@ -203,42 +204,8 @@ const numberObject = object('Number', {
 const stringObject = object('String', { fromCharCode: method(func([], [STRING], { rest: NUMBER })) }, func([ANY], [STRING]));
 const booleanObject = object('Boolean', {}, func([ANY], [BOOL]));
 const timer = func([func([], []), NUMBER], [ANY], { required: 1, rest: ANY });
-/** JS globals that are available without types: everything about them is `any`. */
+/** The type parameter of `transfer`: it gives back what it takes. */
 const MOVED = { kind: 'param', name: 'T' };
-const UNTYPED_GLOBALS = [
-    'Object',
-    'Array',
-    'Date',
-    'RegExp',
-    'Map',
-    'Set',
-    'WeakMap',
-    'WeakSet',
-    'Promise',
-    'Symbol',
-    'Reflect',
-    'Proxy',
-    'Intl',
-    'globalThis',
-    'process',
-    'Buffer',
-    'URL',
-    'URLSearchParams',
-    'TextEncoder',
-    'TextDecoder',
-    'AbortController',
-    'fetch',
-    'structuredClone',
-    'queueMicrotask',
-    'window',
-    'document',
-    'navigator',
-    'location',
-    'localStorage',
-    'sessionStorage',
-    'crypto',
-    'performance',
-];
 export const GLOBAL_VALUES = new Map([
     ['console', console],
     ['Math', math],
@@ -268,6 +235,8 @@ export const GLOBAL_VALUES = new Map([
     // Channels of time, as in Go: the time once after `ms`, or every `ms` until `close(ticks)`.
     ['after', func([NUMBER], [chanOf(NUMBER, 'receive')])],
     ['tick', func([NUMBER], [chanOf(NUMBER)])],
+    // `stream(ch)`: a ReadableStream of the values of a channel (its type: channels.ts).
+    ['stream', func([chanOf(ANY, 'receive')], [ANY])],
     // `cancel(task)` stops a goroutine: it takes the Promise of `go` (channels.ts).
     ['cancel', func([ANY], [])],
     ...[...UNTYPED_GLOBALS, ...BUFFERS].map((name) => [name, ANY]),

package/dist/checker/bytes.d.ts

@@ -1,7 +1,7 @@
 import type * as ast from '../ast.ts';
-import { ChannelChecker } from './channels.ts';
+import { QueueChecker } from './queues.ts';
 import { type Type } from './types.ts';
-export declare abstract class BytesChecker extends ChannelChecker {
+export declare abstract class BytesChecker extends QueueChecker {
     protected checkArrayLiteral(node: ast.ArrayLiteral, expected: Type | null): Type;
     private isElements;
     /** `make([]float64, n)`: a typed array of `n` zeros. */

package/dist/checker/bytes.js

@@ -1,11 +1,11 @@
-import { ChannelChecker } from "./channels.js";
+import { QueueChecker } from "./queues.js";
 import { isUntyped } from "./helpers.js";
 import { holdsBigInts } from "../typed-arrays.js";
 import { BIGINT, isBytes, nonNull, NUMBER, STRING, typedArrayOf, typeToString, UNKNOWN, } from "./types.js";
 // `[]byte`, a Uint8Array, and the other typed arrays, `[]float64`: an array literal where one is
 // expected, `let data []byte = [1, 2]`; and the conversions of Go between text and its UTF-8
 // bytes, `[]byte("rook")` and `string(data)`.
-export class BytesChecker extends ChannelChecker {
+export class BytesChecker extends QueueChecker {
     checkArrayLiteral(node, expected) {
         const typed = expected && nonNull(expected);
         const name = typed && typedArrayOf(typed);

package/dist/checker/channels.d.ts

@@ -3,7 +3,10 @@ import { GoroutineChecker } from './goroutines.ts';
 import { type Type } from './types.ts';
 export declare abstract class ChannelChecker extends GoroutineChecker {
     protected checkChan(node: ast.ChanExpression): Type;
+    protected checkStreamChan(node: ast.StreamChanExpression): Type;
     protected checkSend(node: ast.SendStatement): void;
     protected checkCall(node: ast.CallExpression, callee: Type, expected?: Type | null): Type;
+    /** `stream(ch)`: a ReadableStream of the values of the channel, from the library if it has one. */
+    private streamOf;
     protected checkSelect(node: ast.SelectStatement): void;
 }

package/dist/checker/channels.js

@@ -4,10 +4,11 @@ import { GoroutineChecker } from "./goroutines.js";
 import { isUntyped } from "./helpers.js";
 import { isPromise } from "./promise.js";
 import { BUFFERS } from "./transfer.js";
-import { BOOL, isNullable, nonNull, NUMBER, typeToString } from "./types.js";
+import { ANY, BOOL, ERROR, instantiate, isNullable, nonNull, NUMBER, typeToString, typedArrayOf, UNKNOWN, } from "./types.js";
 // Channels: `chan<number>(10)` makes one, `ch <- v` sends a value, `<-ch` receives one (in
 // operators.ts), `for v in ch` receives them until it is closed (in control-flow.ts), and
 // `select` waits for the first of several. `transfer(x)` moves a buffer to another thread.
+// `chan(stream)` receives the chunks of a ReadableStream, and `stream(ch)` reads a channel.
 /** What `transfer(x)` moves: a buffer, or a view whose buffer moves. */
 const MOVABLE = new Set(BUFFERS);
 function typeName(type) {
@@ -24,6 +25,31 @@ export class ChannelChecker extends GoroutineChecker {
             this.expectAssignable(this.checkValue(node.size, NUMBER), NUMBER, node.size);
         return chanOf(element);
     }
+    // `chan(res.body, 4)`: the channel of the chunks and the one of the error of the stream. A null
+    // stream, such as the body of a response without one, gives a closed channel.
+    checkStreamChan(node) {
+        const type = this.checkValue(node.stream);
+        const stream = isNullable(type) ? nonNull(type) : type;
+        let element = ANY;
+        if (stream.kind === 'object' && typeName(stream) === 'ReadableStream') {
+            element = stream.instanceOf?.args[0] ?? ANY;
+            // The bytes of a body are a Uint8Array<ArrayBuffer>, and a channel takes only its own type:
+            // its values are `[]byte`.
+            const typed = typedArrayOf(element);
+            if (typed !== null)
+                element = this.typedArray(typed);
+        }
+        else if (!isUntyped(stream)) {
+            this.error(`chan(...) takes a ReadableStream, not ${typeToString(type)}; a channel of values is made as chan<T>(size), e.g. chan<number>(10)`, node.stream);
+            if (node.size)
+                this.checkValue(node.size);
+            // `ch = chan(10)` meant `chan<number>(10)`: one error is enough.
+            return UNKNOWN;
+        }
+        if (node.size)
+            this.expectAssignable(this.checkValue(node.size, NUMBER), NUMBER, node.size);
+        return { kind: 'tuple', types: [chanOf(element), chanOf(ERROR, 'receive')] };
+    }
     checkSend(node) {
         const nullChannel = this.inSelectCase;
         this.inSelectCase = false;
@@ -58,6 +84,8 @@ export class ChannelChecker extends GoroutineChecker {
         if (builtin === 'close' && isChan(type) && chanDirection(type) === 'receive') {
             this.error(`cannot close ${typeToString(type)}: it only receives, and a channel is closed by its sender`, argument);
         }
+        if (builtin === 'stream' && isChan(type))
+            return this.streamOf(type, argument);
         if (builtin === 'cancel' && !isUntyped(type) && !isPromise(type)) {
             this.error(`cancel() stops a goroutine: give it the Promise of "go", not ${typeToString(type)}, e.g. "const task = go work(x)" and "cancel(task)"`, argument);
         }
@@ -66,6 +94,16 @@ export class ChannelChecker extends GoroutineChecker {
         }
         return result;
     }
+    /** `stream(ch)`: a ReadableStream of the values of the channel, from the library if it has one. */
+    streamOf(channel, argument) {
+        if (chanDirection(channel) === 'send') {
+            this.error(`stream() reads a channel, and ${typeToString(channel)} only sends; give it a "chan T" or a "<-chan T"`, argument);
+        }
+        const template = this.options.library?.type('ReadableStream');
+        return template?.kind === 'object' && template.typeParams?.length === 1
+            ? instantiate(template, [elementOf(channel)])
+            : ANY;
+    }
     checkSelect(node) {
         this.dropNarrowing(assignedNames(node));
         const entry = this.flow;

package/dist/checker/context.d.ts

@@ -87,6 +87,12 @@ export interface Binding {
     type: Type | null;
     /** For components, which exist only at compile time and are used as tags. */
     component?: ComponentInfo;
+    /**
+     * `const user, err = loadUser(id)` of `(User, error)`: the error has the values that are not null
+     * once it is null, and each of them has the error (error-results.ts).
+     */
+    guards?: Binding[];
+    guardedBy?: Binding;
 }
 export interface ComponentInfo {
     node: ast.ComponentDeclaration;

package/dist/checker/control-flow.d.ts

@@ -17,6 +17,7 @@ export declare abstract class ControlFlowChecker extends StatementChecker {
     protected narrow(node: ast.Expression, assumeTrue: boolean): Narrowing;
     /** `x instanceof Date`: an instance of the class when true, the rest of a union when false. */
     protected narrowInstanceof(left: ast.Expression, right: ast.Expression, assumeTrue: boolean): Narrowing;
+    protected nullError(node: ast.Expression): void;
     protected narrowableBinding(node: ast.Expression): Binding | undefined;
     /** An assignment to a variable ends its narrowing. */
     protected forget(target: ast.Expression): void;

package/dist/checker/control-flow.js

@@ -170,6 +170,14 @@ export class ControlFlowChecker extends StatementChecker {
             if (binding?.type)
                 return [[binding, nonNull(this.flow.get(binding) ?? binding.type)]];
         }
+        // `err == null` when true, `err != null` when false: the values returned with `err` are not
+        // null (error-results.ts).
+        if ((operator === '==' && assumeTrue) || (operator === '!=' && !assumeTrue)) {
+            const target = right.kind === 'NullLiteral' ? left : left.kind === 'NullLiteral' ? right : null;
+            const guards = target ? this.narrowableBinding(target)?.guards : undefined;
+            if (guards)
+                return guards.map((value) => [value, nonNull(this.flow.get(value) ?? value.type)]);
+        }
         if (operator === 'instanceof')
             return this.narrowInstanceof(left, right, assumeTrue);
         if (operator !== '==' && operator !== '!=')
@@ -219,6 +227,15 @@ export class ControlFlowChecker extends StatementChecker {
             : !isAssignable(member, instance));
         return [[binding, union(isNullable(current) ? [...kept, NULL] : kept)]];
     }
+    nullError(node) {
+        const name = node.kind === 'Identifier' ? node.name : null;
+        const error = name !== null ? this.lookupValue(name)?.guardedBy?.name : undefined;
+        this.error(error !== undefined
+            ? `"${name}" may be null until "${error}" is checked: e.g. if ${error} != null { return }`
+            : name !== null
+                ? `"${name}" may be null: check it with "if ${name} != null" or use "?."`
+                : 'this value may be null: check it for null or use "?."', node);
+    }
     narrowableBinding(node) {
         if (node.kind !== 'Identifier')
             return undefined;

package/dist/checker/error-results.d.ts

@@ -0,0 +1,6 @@
+import { type Type } from './types.ts';
+export declare function isErrorType(type: Type): boolean;
+/** Positions of the results that may be null only together with an error: all before it. */
+export declare function guardedByError(results: readonly Type[]): number[];
+/** The types of the unpacked results: those before the error may be null. */
+export declare function unpackedResults(results: readonly Type[]): Type[];

package/dist/checker/error-results.js

@@ -0,0 +1,31 @@
+import { ERROR, isNullable, nullable, typesEqual } from "./types.js";
+// Values returned with an error: in `(User, error)` the function may return `null, err` instead of
+// a User, as long as the error is not null. So where the results are unpacked, the values before
+// the error may be null, and they are not null once the error is found to be null. A result that
+// is nullable itself, as in `(?User, error)`, may be null without an error too.
+export function isErrorType(type) {
+    return typesEqual(type, ERROR);
+}
+/** Positions of the results that may be null only together with an error: all before it. */
+export function guardedByError(results) {
+    if (results.length < 2 || !isErrorType(results.at(-1)))
+        return [];
+    return results.flatMap((type, i) => (i < results.length - 1 && canBeGuarded(type) ? [i] : []));
+}
+/** The types of the unpacked results: those before the error may be null. */
+export function unpackedResults(results) {
+    const guarded = guardedByError(results);
+    return results.map((type, i) => (guarded.includes(i) ? nullable(type) : type));
+}
+function canBeGuarded(type) {
+    switch (type.kind) {
+        case 'any':
+        case 'unknown':
+        case 'void':
+        case 'never':
+        case 'null':
+            return false;
+        default:
+            return !isNullable(type);
+    }
+}

package/dist/checker/expressions.d.ts

@@ -9,6 +9,8 @@ export declare abstract class ExpressionChecker extends FunctionChecker {
     protected abstract checkGo(node: ast.GoExpression): Type;
     /** `chan<number>(10)`; implemented by ChannelChecker. */
     protected abstract checkChan(node: ast.ChanExpression): Type;
+    protected abstract checkStreamChan(node: ast.StreamChanExpression): Type;
+    protected abstract checkQueue(node: ast.QueueExpression): Type;
     /** `[]byte("text")`; implemented by BytesChecker. */
     protected abstract checkConversion(node: ast.ConversionExpression): Type;
     protected abstract checkMake(node: ast.MakeExpression): Type;

package/dist/checker/expressions.js

@@ -67,6 +67,10 @@ export class ExpressionChecker extends FunctionChecker {
                 return this.checkGo(node);
             case 'ChanExpression':
                 return this.checkChan(node);
+            case 'StreamChanExpression':
+                return this.checkStreamChan(node);
+            case 'QueueExpression':
+                return this.checkQueue(node);
             case 'ConversionExpression':
                 return this.checkConversion(node);
             case 'MakeExpression':

package/dist/checker/helpers.js

@@ -137,6 +137,8 @@ export function callName(node) {
     }
     if (node.kind === 'GoExpression')
         return callName(node.call);
+    if (node.kind === 'StreamChanExpression')
+        return 'chan(stream)';
     if (node.kind !== 'CallExpression')
         return 'this expression';
     const { callee } = node;

package/dist/checker/queues.d.ts

@@ -0,0 +1,6 @@
+import type * as ast from '../ast.ts';
+import { ChannelChecker } from './channels.ts';
+import { type Type } from './types.ts';
+export declare abstract class QueueChecker extends ChannelChecker {
+    protected checkQueue(node: ast.QueueExpression): Type;
+}