rooklang 0.3.3 → 0.4.0

package/src/runtime/decode.js

@@ -0,0 +1,221 @@
+// `decode<T>(x)`: JSON text, or a value from JS, checked against the type T, which the compiler
+// writes as data: "number", "string", "bool", "any", { literal: [values] }, { nullable: T },
+// { array: T }, { record: T }, { union: [types] } and $$type(name, fields) for an object. A value
+// that fits is returned as it is, with the fields that T does not have; a nullable field may be
+// missing. The error says where the value does not fit: `decode User: tags[1]: expected string,
+// got 42`.
+
+/** An object type. Its fields come from a function, so that types can refer to each other. */
+export function $$type(name, fields) {
+  let resolved = null;
+
+  return {
+    name,
+    get fields() {
+      return (resolved ??= fields());
+    },
+  };
+}
+
+/** `decode<T>(text)` of a string: the JSON text is parsed, then checked. */
+export function $$decodeJson(text, type) {
+  let value;
+
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    return [null, new Error(`decode ${describe(type)}: invalid JSON: ${error.message}`)];
+  }
+
+  return $$decode(value, type);
+}
+
+/**
+ * `decode<T>(value)` of a value from JS. Without the types of the checker (`rook build --no-check`)
+ * the type is null: then a string is parsed as JSON text, and nothing is checked.
+ */
+export function $$decode(value, type) {
+  if (type === null) return typeof value === 'string' ? $$decodeJson(value, 'any') : [value, null];
+
+  const problem = check(value, type, []);
+
+  if (problem === null) return [value, null];
+
+  const where = problem.path.length > 0 ? `${pathText(problem.path)}: ` : '';
+
+  return [null, new Error(`decode ${describe(type)}: ${where}${problem.message}`)];
+}
+
+const PRIMITIVES = { number: 'number', string: 'string', bool: 'boolean' };
+
+/**
+ * Where and how the value does not fit the type, or null if it does. For a member of a union,
+ * `tagsFirst` checks its fields of literal types first: a member whose tag does not fit reports
+ * that, not another field.
+ */
+function check(value, type, path, tagsFirst = false) {
+  if (typeof type === 'string') {
+    return type === 'any' || typeof value === PRIMITIVES[type] ? null : mismatch(value, type, path);
+  }
+
+  if ('literal' in type) {
+    // Remembered for unions: a tag that fits no member lists the tags of all of them.
+    return type.literal.includes(value)
+      ? null
+      : { ...mismatch(value, type, path), literal: type.literal, value };
+  }
+
+  if ('nullable' in type) {
+    if (value == null) return null;
+
+    const problem = check(value, type.nullable, path);
+
+    // The value itself is of another type: the message names ?T, not T.
+    return problem !== null && problem.path.length === path.length
+      ? mismatch(value, type, path)
+      : problem;
+  }
+
+  if ('array' in type) {
+    if (!Array.isArray(value)) return mismatch(value, type, path);
+
+    for (let i = 0; i < value.length; i++) {
+      const problem = check(value[i], type.array, [...path, i]);
+
+      if (problem !== null) return problem;
+    }
+
+    return null;
+  }
+
+  if ('union' in type) return checkUnion(value, type, path);
+  if (!isObject(value)) return mismatch(value, type, path);
+
+  if ('record' in type) {
+    for (const key of Object.keys(value)) {
+      const problem = check(value[key], type.record, [...path, key]);
+
+      if (problem !== null) return problem;
+    }
+
+    return null;
+  }
+
+  const fields = Object.entries(type.fields);
+
+  if (tagsFirst) fields.sort(([, a], [, b]) => Number(isLiteral(b)) - Number(isLiteral(a)));
+
+  for (const [name, field] of fields) {
+    // Only own fields: a field named `toString` is not the method of every object.
+    if (!Object.hasOwn(value, name)) {
+      if (isOptional(field)) continue;
+
+      return { path: [...path, name], message: 'missing' };
+    }
+
+    const problem = check(value[name], field, [...path, name]);
+
+    if (problem !== null) return problem;
+  }
+
+  return null;
+}
+
+/**
+ * The value fits one of the types. If none fits, the type whose check went deepest into the value
+ * is most likely the one meant, and of those the one whose tag fits: `{ kind: "circle", r: "2" }`
+ * of `Circle | Square` is a Circle, so its problem is the one reported. When no tag fits, the
+ * message lists them all: `kind: expected "circle" | "square", got "oval"`.
+ */
+function checkUnion(value, type, path) {
+  const problems = [];
+
+  for (const member of type.union) {
+    const problem = check(value, member, path, true);
+
+    if (problem === null) return null;
+    problems.push(problem);
+  }
+
+  const depth = Math.max(...problems.map((problem) => problem.path.length));
+
+  if (depth === path.length) return mismatch(value, type, path);
+
+  const deepest = problems.filter((problem) => problem.path.length === depth);
+  const fitting = deepest.find((problem) => !problem.literal);
+
+  if (fitting) return fitting;
+
+  const [first] = deepest;
+  const same = deepest.filter((problem) => pathText(problem.path) === pathText(first.path));
+  const literal = [...new Set(same.flatMap((problem) => problem.literal))];
+
+  return { ...mismatch(first.value, { literal }, first.path), literal, value: first.value };
+}
+
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isLiteral(type) {
+  return typeof type === 'object' && 'literal' in type;
+}
+
+function isOptional(type) {
+  return type === 'any' || (typeof type === 'object' && 'nullable' in type);
+}
+
+function mismatch(value, type, path) {
+  return { path, message: `expected ${describe(type)}, got ${shown(value)}` };
+}
+
+/** The type as Rook writes it: `[]string`, `?User`, `"admin" | "user"`. */
+function describe(type) {
+  if (typeof type === 'string') return type;
+  if ('literal' in type) return type.literal.map((value) => JSON.stringify(value)).join(' | ');
+  if ('nullable' in type) return `?${grouped(type.nullable)}`;
+  if ('array' in type) return `[]${grouped(type.array)}`;
+  if ('record' in type) return `{ [key string]: ${describe(type.record)} }`;
+  if ('union' in type) return type.union.map(describe).join(' | ');
+
+  return type.name;
+}
+
+function grouped(type) {
+  const several = typeof type === 'object' && ('union' in type || type.literal?.length > 1);
+
+  return several ? `(${describe(type)})` : describe(type);
+}
+
+/** The value in a message: a primitive itself, a long string cut, and the kind of anything else. */
+function shown(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'an array';
+
+  switch (typeof value) {
+    case 'string':
+      return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+
+    case 'number':
+    case 'boolean':
+      return String(value);
+
+    case 'object':
+      return 'an object';
+
+    default:
+      return typeof value;
+  }
+}
+
+/** `tags[1]`, `boss.name`, `["first name"]`. */
+function pathText(path) {
+  return path
+    .map((key, i) => {
+      if (typeof key === 'number') return `[${key}]`;
+      if (/^[A-Za-z_$][\w$]*$/.test(key)) return i === 0 ? key : `.${key}`;
+
+      return `[${JSON.stringify(key)}]`;
+    })
+    .join('');
+}

package/src/runtime/go.js

@@ -9,6 +9,7 @@ import {
   $$gone,
   $$incoming,
   $$post,
+  $$reclassed,
   $$registry,
   $$transfer,
 } from './threads.js';
@@ -142,6 +143,7 @@ export function $$pool() {
       worker.owns = data.owns;
     } else if ('returned' in data) {
       $$adopt(data);
+      $$reclassed(data);
 
       const call = calls.get(data.returned);
 
@@ -311,6 +313,7 @@ export async function $$serve(functions) {
     if ('gone' in data) return $$gone(data.gone);
     setTimeout(free);
     $$adopt(data.args);
+    $$reclassed(data);
 
     const { main } = registry;
 

package/src/runtime/index.js

@@ -3,11 +3,18 @@
 // The compiler can also put the parts that a module needs into the module itself (runtime.ts).
 
 export * from './chan.js';
+export * from './channel.js';
+export * from './classes.js';
 export * from './core.js';
+export * from './decode.js';
 export * from './go.js';
 export * from './markup.js';
 export * from './queue.js';
 export * from './select.js';
+export * from './shared.js';
+export * from './signals.js';
 export * from './streams.js';
 export * from './threads.js';
 export * from './timers.js';
+export * from './topic.js';
+export * from './try.js';

package/src/runtime/markup.js

@@ -1,10 +1,10 @@
 // Markup: the owners of the blocks that `{if}`, `{switch}` and `{for}` remove, the
-// `mount()` of components, the blocks themselves, elements and the CSS of components.
+// `mount` of components, the blocks themselves, elements and the CSS of components.
 
 import { $$runDeferred } from './core.js';
 
-// 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.
+// Owners of markup that `{if}`, `{switch}` and `{for}` may remove: what the `mount` and `effect`
+// of its components deferred, 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.
 export const $$owner = Symbol.for('rook.owner');
@@ -36,15 +36,17 @@ export function $$onRemove(cleanup) {
   globalThis[$$owner]?.cleanups.push(cleanup);
 }
 
-// `mount() { ... }` of a component: runs when its markup is in the document. That is checked after
+// `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.
+// before that never mounts. What its `defer`s put into `cleanups` runs when the owner is removed;
+// they are added to the owner once it mounts, so the cleanups of the decorators, which mount after
+// the component, run before those of the component.
 export const $$waiting = new Set();
 export let $$observer = null;
 
-export function $$mount(node, mount) {
-  const entry = { node, mount, owner: globalThis[$$owner] };
+export function $$mount(node, mount, cleanups) {
+  const entry = { node, mount, cleanups, owner: globalThis[$$owner] };
 
   entry.owner?.cleanups.push(() => $$waiting.delete(entry));
   queueMicrotask(() => $$tryMount(entry));
@@ -65,9 +67,8 @@ export function $$tryMount(entry) {
     return;
   }
 
-  const cleanup = entry.mount();
-
-  if (typeof cleanup === 'function') entry.owner?.cleanups.push(cleanup);
+  entry.mount();
+  if (entry.cleanups) entry.owner?.cleanups.push(() => $$runDeferred(entry.cleanups.splice(0)));
 }
 
 export function $$mountWaiting() {
@@ -216,8 +217,10 @@ export function $$dynamic(component, create) {
 
 // `{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.
-export function $$list(items, create) {
+// moved into place, others are created or removed. With `key`, of `with key item.id`, they are
+// found by the key instead, so an item replaced by another with the same key keeps its block,
+// which gets the new item.
+export function $$list(items, create, key = (item) => item) {
   const end = document.createTextNode('');
   const fragment = document.createDocumentFragment();
 
@@ -236,24 +239,25 @@ export function $$list(items, create) {
     const old = new Map();
 
     for (const block of blocks) {
-      const same = old.get(block.item);
+      const same = old.get(block.key);
 
       if (same) same.push(block);
-      else old.set(block.item, [block]);
+      else old.set(block.key, [block]);
     }
 
     const next = [];
     let index = 0;
 
     for (const item of items()) {
-      let block = old.get(item)?.shift();
+      const id = key(item, index);
+      let block = old.get(id)?.shift();
 
       if (block) {
-        block.update?.(index);
+        block.update?.(index, item);
       } else {
         const [[content, blockUpdate], remove] = $$owned(() => create(item, index));
 
-        block = { item, start: document.createTextNode(''), end: document.createTextNode('') };
+        block = { key: id, start: document.createTextNode(''), end: document.createTextNode('') };
         block.update = blockUpdate;
         block.remove = remove;
         block.content = document.createDocumentFragment();
@@ -315,6 +319,12 @@ export function $$svgElement(tag, attributes) {
   return element;
 }
 
+// The class of `class={[styles.tab, active ? styles.active : null]}`: the classes that are not
+// null or empty, separated by spaces.
+export function $$classes(list) {
+  return list.filter((each) => each).join(' ');
+}
+
 // Sets an attribute whose value may be null: then the attribute is removed.
 export function $$attribute(element, name, value) {
   if (value == null) element.removeAttribute(name);

package/src/runtime/select.js

@@ -3,12 +3,13 @@
 // channels of a select.
 
 import { $$finish, $$pump, $$zero } from './chan.js';
-import { $$ask, $$ownerOf, $$pin, $$post, $$registry, $$stopped } from './threads.js';
+import { $$ask, $$isEmpty, $$ownerOf, $$pin, $$post, $$registry, $$stopped } from './threads.js';
 
 // `select`: the index of the case that went on, and what it received. A case is { channel } to
-// receive or { channel, value } to send; from another thread, { channel, send, value }. One that
-// can go on at once wins, a random one as in Go; else `default`, -1, if there is one; else the
-// first that can go on later. A case with a null channel never goes on.
+// receive or { channel, value } to send, with the zero value that Channel.EMPTY gives, if it is
+// not null; from another thread, { channel, send, value }. One that can go on at once wins, a
+// random one as in Go; else `default`, -1, if there is one; else the first that can go on later.
+// A case with a null channel never goes on, and one with Channel.EMPTY always can.
 export async function $$select(cases, hasDefault) {
   const registry = $$registry();
   const all = cases.map((each, i) => ({
@@ -16,12 +17,13 @@ export async function $$select(cases, hasDefault) {
     id: typeof each.channel === 'string' ? each.channel : (each.channel?.$$chan ?? null),
     send: each.send ?? 'value' in each,
     value: each.value,
+    zero: each.zero ?? null,
   }));
   const live = all.filter(({ id }) => id !== null);
-  const owners = new Set(live.map(({ id }) => $$ownerOf(id)));
+  const owners = new Set(live.filter(({ id }) => !$$isEmpty(id)).map(({ id }) => $$ownerOf(id)));
 
   // The channels of one other thread: the select runs there.
-  if (owners.size === 1 && !owners.has(registry.key)) {
+  if (owners.size === 1 && !owners.has(registry.key) && live.every(({ id }) => !$$isEmpty(id))) {
     const [owner] = owners;
 
     return $$ask(owner, {
@@ -34,10 +36,13 @@ export async function $$select(cases, hasDefault) {
   const order = live.map(({ i }) => i).sort(() => Math.random() - 0.5);
 
   for (const i of order) {
-    const { id, send, value } = all[i];
+    const { id, send, value, zero } = all[i];
     const owner = $$ownerOf(id);
-    const ready =
-      owner === registry.key
+    const ready = $$isEmpty(id)
+      ? send
+        ? []
+        : [zero, false]
+      : owner === registry.key
         ? $$try(id, send, value)
         : await $$ask(owner, { op: 'try', channel: id, send, value });
 

package/src/runtime/shared.js

@@ -0,0 +1,17 @@
+// State of a module, `state items []Item = []` at its top level: the set of the updates of the
+// components that read it, which every change of it runs.
+
+import { $$onRemove } from './markup.js';
+
+// A component adds its update while it is on the page: `{if}`, `{switch}` or `{for}` that removes
+// it takes the update away.
+export function $$watch(listeners, update) {
+  listeners.add(update);
+  $$onRemove(() => listeners.delete(update));
+}
+
+// After a change of the state: the updates run on a copy, since one may remove a component, or
+// add one, that listens too.
+export function $$changed(listeners) {
+  for (const update of [...listeners]) update();
+}

package/src/runtime/signals.js

@@ -0,0 +1,59 @@
+// Signals of the process and AbortSignal as channels: `signal(...names)`, `done(abortSignal)` and
+// `abortSignal(ch)`, as signal.Notify and the Done() of a context are in Go.
+
+import { $$chan, $$closeHere, $$receive } from './chan.js';
+import { $$try } from './select.js';
+import { $$registry } from './threads.js';
+
+// `signal("SIGINT", "SIGTERM")`: a channel that gets the name of each signal that comes. While it
+// listens, the signals do not end the process, and it keeps the program running, as a tick does;
+// `close(ch)` stops it, and the signals do what they did before. A signal that finds the last one
+// not received yet is dropped. Only the main thread of Node gets the signals of the process.
+export function $$signal(...names) {
+  // Node's own, which a browser does not have.
+  const { process } = globalThis;
+
+  if (process === undefined) throw new Error('signal() needs Node: a browser has no signals');
+
+  const channel = $$chan(1, '');
+  const listener = (name) => $$try(channel.$$chan, true, name);
+  // A listener of a signal does not keep the program running, and a timer that never fires does.
+  const timer = setInterval(() => {}, 2 ** 31 - 1);
+
+  for (const name of names) process.on(name, listener);
+  $$registry().states.get(channel.$$chan).onClose = () => {
+    clearInterval(timer);
+    for (const name of names) process.off(name, listener);
+  };
+
+  return channel;
+}
+
+// `done(signal)`: a channel that gets the reason of an AbortSignal when it aborts, and is closed
+// then, so that `case <-done(request.signal):` goes on once the request is cancelled.
+export function $$done(signal) {
+  const channel = $$chan(1, null);
+  const abort = () => {
+    $$try(channel.$$chan, true, signal.reason);
+    $$closeHere(channel.$$chan);
+  };
+
+  if (signal.aborted) abort();
+  else signal.addEventListener('abort', abort, { once: true });
+
+  return channel;
+}
+
+// `abortSignal(ch)`: an AbortSignal that aborts when the channel gets a value, with the value as
+// its reason, or is closed, for `fetch(url, { signal: abortSignal(stop) })`. It receives that one
+// value, as any receiver of the channel would.
+export function $$abortSignal(channel) {
+  const controller = new AbortController();
+
+  $$receive(channel, true).then(
+    ([value, ok]) => controller.abort(ok ? value : undefined),
+    (error) => controller.abort(error),
+  );
+
+  return controller.signal;
+}

package/src/runtime/threads.js

@@ -4,6 +4,7 @@
 // modules; the operations of a thread on the channels of another go straight to that thread
 // through a MessagePort, which the main thread sets up on the first need (go.js).
 
+import { $$classOf, $$reclass } from './classes.js';
 import { $$Queue } from './queue.js';
 
 // The state of this thread that its modules share: the channels it made, its ports to the other
@@ -29,6 +30,12 @@ export function $$registry() {
   });
 }
 
+// Channel.EMPTY, the zero value of channel types, has this id in every thread: it is closed, and
+// no thread keeps it (channel.js).
+export function $$isEmpty(id) {
+  return id === 'empty';
+}
+
 // The key of the thread that made a channel, which keeps what it holds.
 export function $$ownerOf(id) {
   return id.slice(0, id.lastIndexOf(':'));
@@ -42,9 +49,11 @@ export function $$post(key, message) {
 
   if (registry.gone.has(key)) return;
 
-  const { channels, moved } = $$walk(message);
+  const { channels, moved, instances } = $$walk(message);
 
   for (const channel of channels) $$hold(channel.$$chan, 1);
+  // The copies of the instances of data classes are listed in the copy, by reference.
+  if (instances.length > 0) message = { ...message, $$instances: instances };
 
   const port = registry.ports.get(key);
 
@@ -136,6 +145,7 @@ export function $$incoming(key, data) {
   const registry = $$registry();
 
   $$adopt(data);
+  $$reclassed(data);
   if ('answer' in data) {
     const request = registry.requests.get(data.answer);
 
@@ -166,6 +176,11 @@ export function $$hold(id, count) {
   if (state.holders <= 0) registry.states.delete(id);
 }
 
+// A message with copies of the instances of data classes gives them their classes back.
+export function $$reclassed(data) {
+  if (data.$$instances) $$reclass(data.$$instances);
+}
+
 export function $$adopt(value) {
   const { held } = $$registry();
 
@@ -175,11 +190,19 @@ export function $$adopt(value) {
 // A copy in this thread. One that `own` the runtime, such as the arguments of `go` that wait for
 // a worker, moves its buffers on.
 export function $$copy(value, own = false) {
-  const { channels, moved } = $$walk(value);
+  const { channels, moved, instances } = $$walk(value);
 
   for (const channel of channels) $$hold(channel.$$chan, 1);
 
-  const copy = structuredClone(value, { transfer: moved });
+  const { copy, $$instances } = structuredClone(
+    { copy: value, $$instances: instances },
+    {
+      transfer: moved,
+    },
+  );
+
+  $$reclass($$instances);
+
   const { held } = $$registry();
 
   for (const channel of $$walk(copy, own).channels) held.register(channel, channel.$$chan);
@@ -200,7 +223,7 @@ export function $$transfer(value) {
 export function $$walk(
   value,
   own = false,
-  found = { channels: new Set(), moved: [] },
+  found = { channels: new Set(), moved: [], instances: [] },
   seen = new Set(),
 ) {
   if (typeof value !== 'object' || value === null || seen.has(value)) return found;
@@ -221,8 +244,12 @@ export function $$walk(
   }
 
   if (Array.isArray(value.$$queue)) Object.setPrototypeOf(value, $$Queue.prototype);
+
+  const id = $$classOf(value);
+
+  if (id !== undefined) found.instances.push([value, id]);
   if (typeof value.$$chan === 'string') {
-    found.channels.add(value);
+    if (!$$isEmpty(value.$$chan)) found.channels.add(value);
 
     return found;
   }