@bablr/agast-helpers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Conrad Buck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# @bablr/agast-helpers
+
+Helper functions for working with agAST trees

package/lib/builders.js

@@ -0,0 +1,229 @@
+const { freeze } = Object;
+
+export const buildReference = (name, isArray) => {
+  return freeze({ type: 'Reference', value: freeze({ name, isArray }) });
+};
+
+export const buildNull = () => {
+  return freeze({ type: 'Null', value: undefined });
+};
+
+export const buildGap = () => {
+  return freeze({ type: 'Gap', value: undefined });
+};
+
+export const buildEmbedded = (node) => {
+  return freeze({ type: 'Embedded', value: node });
+};
+
+export const buildDoctypeTag = (attributes) => {
+  return freeze({
+    type: 'DoctypeTag',
+    value: { doctype: 'cstml', version: 0, attributes: freeze(attributes) },
+  });
+};
+
+export const buildNodeOpenTag = (flags, language, type, intrinsicValue, attributes = {}) => {
+  let { token, trivia, escape, expression } = flags;
+
+  if (!type) throw new Error();
+
+  token = !!token;
+  trivia = !!trivia;
+  escape = !!escape;
+  expression = !!expression;
+  let intrinsic = !!intrinsicValue;
+
+  return freeze({
+    type: 'OpenNodeTag',
+    value: freeze({
+      flags: freeze({ token, trivia, escape, intrinsic, expression }),
+      language,
+      type,
+      intrinsicValue,
+      attributes,
+    }),
+  });
+};
+
+export const buildFragmentOpenTag = (flags = nodeFlags, language) => {
+  let { token, trivia, escape } = flags;
+
+  token = !!token;
+  trivia = !!trivia;
+  escape = !!escape;
+
+  return freeze({
+    type: 'OpenFragmentTag',
+    value: freeze({ flags: freeze({ token, trivia, escape }) }),
+  });
+};
+
+export const buildNodeCloseTag = (type = null, language = null) => {
+  return freeze({ type: 'CloseNodeTag', value: freeze({ language, type }) });
+};
+
+export const buildFragmentCloseTag = () => {
+  return freeze({ type: 'CloseFragmentTag', value: freeze({}) });
+};
+
+const isString = (val) => typeof val === 'string';
+
+export const buildLiteral = (value) => {
+  if (!isString(value)) throw new Error('invalid literal');
+  return freeze({ type: 'Literal', value });
+};
+
+export const buildNodeWithFlags = (
+  flags,
+  language,
+  type,
+  children = [],
+  properties = {},
+  attributes = {},
+) =>
+  freeze({
+    flags,
+    language,
+    type,
+    children: freeze(children),
+    properties: freeze(properties),
+    attributes: freeze(attributes),
+  });
+
+export const nodeFlags = freeze({
+  token: false,
+  escape: false,
+  trivia: false,
+  intrinsic: false,
+  expression: false,
+});
+
+export const buildNode = (language, type, children = [], properties = {}, attributes = {}) =>
+  freeze({
+    flags: nodeFlags,
+    language,
+    type,
+    children: freeze(children),
+    properties: freeze(properties),
+    attributes: freeze(attributes),
+  });
+
+export const syntacticFlags = freeze({
+  token: true,
+  escape: false,
+  trivia: false,
+  intrinsic: false,
+  expression: false,
+});
+
+export const buildSyntacticNode = (language, type, value, attributes = {}) =>
+  freeze({
+    flags: syntacticFlags,
+    language,
+    type,
+    children: [buildLiteral(value)],
+    properties: freeze({}),
+    attributes: freeze(attributes),
+  });
+
+export const syntacticIntrinsicFlags = freeze({
+  token: true,
+  escape: false,
+  trivia: false,
+  intrinsic: true,
+  expression: false,
+});
+export const buildSyntacticIntrinsicNode = (language, type, value, attributes = {}) =>
+  freeze({
+    flags: syntacticIntrinsicFlags,
+    language,
+    type,
+    children: [buildLiteral(value)],
+    properties: freeze({}),
+    attributes: freeze(attributes),
+  });
+
+export const escapeFlags = freeze({
+  token: false,
+  escape: true,
+  trivia: false,
+  intrinsic: false,
+  expression: false,
+});
+
+export const buildEscapeNode = (language, type, children = [], properties = {}, attributes = {}) =>
+  freeze({
+    flags: escapeFlags,
+    language,
+    type,
+    children: freeze(children),
+    properties: freeze(properties),
+    attributes: freeze(attributes),
+  });
+
+export const syntacticEscapeFlags = freeze({
+  token: true,
+  escape: true,
+  trivia: false,
+  intrinsic: false,
+  expression: false,
+});
+
+export const buildSyntacticEscapeNode = (
+  language,
+  type,
+  children = [],
+  properties = {},
+  attributes = {},
+) =>
+  freeze({
+    flags: syntacticEscapeFlags,
+    language,
+    type,
+    children: freeze(children),
+    properties: freeze(properties),
+    attributes: freeze(attributes),
+  });
+
+export const syntacticTriviaFlags = freeze({
+  token: true,
+  escape: false,
+  trivia: true,
+  intrinsic: false,
+  expression: false,
+});
+
+export const buildSyntacticTriviaNode = (
+  language,
+  type,
+  children = [],
+  properties = {},
+  attributes = {},
+) =>
+  freeze({
+    flags: syntacticTriviaFlags,
+    language,
+    type,
+    children: freeze(children),
+    properties: freeze(properties),
+    attributes: freeze(attributes),
+  });
+
+export const triviaFlags = freeze({
+  token: false,
+  escape: false,
+  trivia: true,
+  intrinsic: false,
+  expression: false,
+});
+
+export const buildTriviaNode = (language, type, children = [], properties = {}, attributes = {}) =>
+  freeze({
+    flags: triviaFlags,
+    language,
+    type,
+    children: freeze(children),
+    properties: freeze(properties),
+    attributes: freeze(attributes),
+  });

package/lib/path.js

@@ -0,0 +1,16 @@
+export const parsePath = (str) => {
+  const isArray = str.endsWith('[]');
+  const name = isArray ? str.slice(0, -2) : str;
+
+  if (!/^\w+$/.test(name)) throw new Error();
+
+  return { isArray, name };
+};
+
+export const printPath = (path) => {
+  if (!path) return null;
+
+  const { isArray, name } = path;
+
+  return `${name}${isArray ? '[]' : ''}`;
+};

package/lib/print.js

@@ -0,0 +1,198 @@
+const { isInteger, isFinite } = Number;
+const { isArray } = Array;
+const isString = (val) => typeof val === 'string';
+const isNumber = (val) => typeof val === 'number';
+
+export const printExpression = (expr) => {
+  if (isString(expr)) {
+    return printString(expr);
+  } else if (expr == null || typeof expr === 'boolean') {
+    return String(expr);
+  } else if (isNumber(expr)) {
+    if (!isFinite(expr)) {
+      return expr === -Infinity ? '-Infinity' : '+Infinity';
+    } else if (isInteger(expr)) {
+      return String(expr);
+    } else {
+      throw new Error();
+    }
+  } else if (isArray(expr)) {
+    return `[${expr.map((v) => printExpression(v)).join(', ')}]`;
+  } else if (typeof expr === 'object') {
+    return `{${Object.entries(expr).map(([k, v]) => `${k}: ${printExpression(v)}`)}}`;
+  } else {
+    throw new Error();
+  }
+};
+
+export const printAttributes = (attributes) => {
+  return Object.entries(attributes)
+    .map(([k, v]) => (v === true ? k : v === false ? `!${k}` : `${k}=${printExpression(v)}`))
+    .join(' ');
+};
+
+export const printLanguage = (language) => {
+  if (isString(language)) {
+    return printSingleString(language);
+  } else {
+    return language.join('.');
+  }
+};
+
+export const printTagPath = (language, type) => {
+  return language?.length ? `${printLanguage(language)}:${type}` : type;
+};
+
+const escapeReplacer = (esc) => {
+  if (esc === '\r') {
+    return '\\r';
+  } else if (esc === '\n') {
+    return '\\n';
+  } else if (esc === '\t') {
+    return '\\t';
+  } else if (esc === '\0') {
+    return '\\0';
+  } else {
+    return `\\${esc}`;
+  }
+};
+
+export const printSingleString = (str) => {
+  return `'${str.replace(/['\\\0\r\n\t]/g, escapeReplacer)}'`;
+};
+
+export const printDoubleString = (str) => {
+  return `"${str.replace(/["\\\0\r\n\t]/g, escapeReplacer)}"`;
+};
+
+export const printString = (str) => {
+  return str === "'" ? printDoubleString(str) : printSingleString(str);
+};
+
+export const printGap = (terminal) => {
+  if (terminal?.type !== 'Gap') throw new Error();
+
+  return `<//>`;
+};
+
+export const printReference = (terminal) => {
+  if (terminal?.type !== 'Reference') throw new Error();
+
+  const { name, isArray } = terminal.value;
+  const pathBraces = isArray ? '[]' : '';
+
+  return `${name}${pathBraces}:`;
+};
+
+export const printNull = (terminal) => {
+  if (terminal?.type !== 'Null') throw new Error();
+
+  return 'null';
+};
+
+export const printType = (type) => {
+  return typeof type === 'string'
+    ? type
+    : typeof type === 'symbol'
+    ? `$${type.description.replace('@bablr/', '')}`
+    : String(type);
+};
+
+export const printDoctypeTag = (terminal) => {
+  if (terminal?.type !== 'DoctypeTag') throw new Error();
+
+  let { doctype, version, attributes } = terminal.value;
+
+  attributes = attributes ? ` ${printAttributes(attributes)}` : '';
+
+  return `<!${version}:${doctype}${attributes}>`;
+};
+
+export const printLiteral = (terminal) => {
+  if (terminal?.type !== 'Literal') throw new Error();
+
+  return printString(terminal.value);
+};
+
+export const printFlags = (flags) => {
+  const hash = flags.trivia ? '#' : '';
+  const star = flags.token ? '*' : '';
+  const at = flags.escape ? '@' : '';
+  const plus = flags.expression ? '+' : '';
+
+  if (flags.escape && flags.trivia) throw new Error('Node cannot be escape and trivia');
+
+  return `${hash}${star}${at}${plus}`;
+};
+
+export const printOpenNodeTag = (terminal) => {
+  if (terminal?.type !== 'OpenNodeTag') throw new Error();
+
+  const { flags, language: tagLanguage, type, intrinsicValue, attributes } = terminal.value;
+
+  if (intrinsicValue && !flags.intrinsic) throw new Error();
+
+  const printedAttributes = attributes && printAttributes(attributes);
+  const attributesFrag = printedAttributes ? ` ${printedAttributes}` : '';
+  const intrinsicFrag = flags.intrinsic ? ` ${printString(intrinsicValue)}` : '';
+  const selfCloser = flags.intrinsic ? ' /' : '';
+
+  return `<${printFlags(flags)}${printTagPath(
+    tagLanguage,
+    type,
+  )}${intrinsicFrag}${attributesFrag}${selfCloser}>`;
+};
+
+export const printOpenFragmentTag = (terminal) => {
+  if (terminal?.type !== 'OpenFragmentTag') throw new Error();
+
+  let { flags } = terminal.value;
+
+  return `<${printFlags(flags)}>`;
+};
+
+export const printCloseNodeTag = (terminal) => {
+  if (terminal?.type !== 'CloseNodeTag') throw new Error();
+
+  return `</>`;
+};
+
+export const printCloseFragmentTag = (terminal) => {
+  if (terminal?.type !== 'CloseFragmentTag') throw new Error();
+
+  return `</>`;
+};
+
+export const printTerminal = (terminal) => {
+  switch (terminal?.type || 'Null') {
+    case 'Null':
+      return printNull(terminal);
+
+    case 'Gap':
+      return printGap(terminal);
+
+    case 'Literal':
+      return printLiteral(terminal);
+
+    case 'DoctypeTag':
+      return printDoctypeTag(terminal);
+
+    case 'Reference':
+      return printReference(terminal);
+
+    case 'OpenNodeTag':
+      return printOpenNodeTag(terminal);
+
+    case 'OpenFragmentTag':
+      return printOpenFragmentTag(terminal);
+
+    case 'CloseNodeTag':
+      return printCloseNodeTag(terminal);
+
+    case 'CloseFragmentTag':
+      return printCloseFragmentTag(terminal);
+
+    default:
+      throw new Error();
+  }
+};

package/lib/shorthand.js

@@ -0,0 +1,59 @@
+import {
+  buildReference,
+  buildGap,
+  buildEmbedded,
+  buildNodeOpenTag,
+  buildFragmentOpenTag,
+  buildNodeCloseTag,
+  buildFragmentCloseTag,
+  buildLiteral,
+  buildNode,
+  buildSyntacticNode,
+  buildSyntacticIntrinsicNode,
+  buildEscapeNode,
+  buildSyntacticEscapeNode,
+  buildSyntacticTriviaNode,
+  buildTriviaNode,
+} from './builders.js';
+
+export * from './builders.js';
+
+const { isArray } = Array;
+
+const stripArray = (val) => {
+  if (isArray(val)) {
+    if (val.length > 1) {
+      throw new Error();
+    }
+    return val[0];
+  } else {
+    return val;
+  }
+};
+
+export const ref = (path) => {
+  if (isArray(path)) {
+    const pathIsArray = path[0].endsWith('[]');
+    const name = pathIsArray ? path[0].slice(0, -2) : path[0];
+    return buildReference(name, pathIsArray);
+  } else {
+    const { name, isArray: pathIsArray } = path;
+    return buildReference(name, pathIsArray);
+  }
+};
+
+export const lit = (str) => buildLiteral(stripArray(str));
+
+export const gap = buildGap;
+export const embedded = buildEmbedded;
+export const nodeOpen = buildNodeOpenTag;
+export const fragOpen = buildFragmentOpenTag;
+export const nodeClose = buildNodeCloseTag;
+export const fragClose = buildFragmentCloseTag;
+export const node = buildNode;
+export const s_node = buildSyntacticNode;
+export const s_i_node = buildSyntacticIntrinsicNode;
+export const e_node = buildEscapeNode;
+export const s_e_node = buildSyntacticEscapeNode;
+export const s_t_node = buildSyntacticTriviaNode;
+export const t_node = buildTriviaNode;

package/lib/stream.js

@@ -0,0 +1,276 @@
+import { printTerminal } from './print.js';
+export * from './print.js';
+
+export const getStreamIterator = (obj) => {
+  return obj[Symbol.for('@@streamIterator')]?.() || obj[Symbol.iterator]?.();
+};
+
+export class SyncGenerator {
+  constructor(embeddedGenerator) {
+    if (!embeddedGenerator.next) throw new Error();
+
+    this.generator = embeddedGenerator;
+  }
+
+  next(value) {
+    const step = this.generator.next(value);
+
+    if (step instanceof Promise) {
+      throw new Error('invalid embedded generator');
+    }
+
+    if (step.done) {
+      return { value: undefined, done: true };
+    } else if (step.value instanceof Promise) {
+      throw new Error('sync generators cannot resolve promises');
+    } else {
+      const { value } = step;
+      return { value, done: false };
+    }
+  }
+
+  return(value) {
+    const step = this.generator.return(value);
+    if (step instanceof Promise) {
+      throw new Error('invalid embedded generator');
+    }
+
+    if (step.value instanceof Promise) {
+      throw new Error('sync generators cannot resolve promises');
+    }
+    return step;
+  }
+
+  [Symbol.iterator]() {
+    return this;
+  }
+}
+
+export class AsyncGenerator {
+  constructor(embeddedGenerator) {
+    this.generator = embeddedGenerator;
+  }
+
+  next(value) {
+    const step = this.generator.next(value);
+
+    if (step instanceof Promise) {
+      throw new Error('invalid embedded generator');
+    }
+
+    if (step.done) {
+      return Promise.resolve({ value: undefined, done: true });
+    } else if (step.value instanceof Promise) {
+      return step.value.then((value) => {
+        return this.next(value);
+      });
+    } else {
+      const { value } = step;
+      return Promise.resolve({ value, done: false });
+    }
+  }
+
+  return(value) {
+    const result = this.generator.return(value);
+    if (result instanceof Promise) {
+      throw new Error('sync generators cannot resolve promises');
+    }
+    return result;
+  }
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+}
+
+export class StreamGenerator {
+  constructor(embeddedGenerator) {
+    this.generator = embeddedGenerator;
+  }
+
+  next(value) {
+    const step = this.generator.next(value);
+
+    if (step.done) {
+      return { value: undefined, done: true };
+    } else if (step.value instanceof Promise) {
+      return step.value.then((value) => {
+        return this.next(value);
+      });
+    } else {
+      const { value } = step;
+      return { value, done: false };
+    }
+  }
+
+  return(value) {
+    return this.generator.return(value);
+  }
+
+  [Symbol.for('@@streamIterator')]() {
+    return this;
+  }
+}
+
+export class StreamIterable {
+  constructor(embeddedStreamIterable) {
+    this.iterable = embeddedStreamIterable;
+  }
+
+  [Symbol.iterator]() {
+    return new SyncGenerator(this.iterable);
+  }
+
+  [Symbol.asyncIterator]() {
+    return new AsyncGenerator(this.iterable);
+  }
+
+  [Symbol.for('@@streamIterator')]() {
+    return new StreamGenerator(this.iterable);
+  }
+}
+
+export const maybeWait = (maybePromise, callback) => {
+  if (maybePromise instanceof Promise) {
+    return maybePromise.then(callback);
+  } else {
+    return callback(maybePromise);
+  }
+};
+
+export const printCSTML = (terminals) => {
+  if (!terminals) {
+    return '<//>';
+  }
+
+  let printed = '';
+
+  for (const terminal of terminals) {
+    printed += printTerminal(terminal);
+  }
+
+  return printed;
+};
+
+export const printPrettyCSTML = (terminals, indent = '  ') => {
+  if (!terminals) {
+    return '<//>';
+  }
+
+  let printed = '';
+  let indentLevel = 0;
+  let first = true;
+
+  for (const terminal of terminals) {
+    const inline =
+      terminal.type === 'Null' ||
+      terminal.type === 'Gap' ||
+      (terminal.type === 'OpenNodeTag' && terminal.value.flags.intrinsic);
+
+    if (!first && !inline) {
+      printed += '\n';
+    }
+
+    if (['CloseNodeTag', 'CloseFragmentTag'].includes(terminal.type)) {
+      indentLevel--;
+    }
+
+    if (!inline) {
+      printed += indent.repeat(indentLevel);
+    } else {
+      printed += ' ';
+    }
+    printed += printTerminal(terminal);
+
+    if (
+      terminal.type === 'OpenFragmentTag' ||
+      (terminal.type === 'OpenNodeTag' && !terminal.value.flags.intrinsic)
+    ) {
+      indentLevel++;
+    }
+
+    first = false;
+  }
+
+  return printed;
+};
+
+export const getCooked = (terminals) => {
+  let cooked = '';
+
+  for (const terminal of terminals) {
+    switch (terminal.type) {
+      case 'Reference': {
+        throw new Error('cookable nodes must not contain other nodes');
+      }
+
+      case 'OpenNodeTag': {
+        const { flags, attributes } = terminal.value;
+
+        if (!(flags.trivia || (flags.escape && attributes.cooked))) {
+          throw new Error('cookable nodes must not contain other nodes');
+        }
+
+        if (flags.escape) {
+          const { cooked: cookedValue } = terminal.value.attributes;
+
+          if (!cookedValue) throw new Error('cannot cook string: it contains uncooked escapes');
+
+          cooked += cookedValue;
+        }
+
+        break;
+      }
+
+      case 'Literal': {
+        cooked += terminal.value;
+        break;
+      }
+
+      default: {
+        throw new Error();
+      }
+    }
+  }
+
+  return cooked;
+};
+
+export const printSource = (terminals) => {
+  let printed = '';
+
+  for (const terminal of terminals) {
+    if (terminal.type === 'Literal') {
+      printed += terminal.value;
+    } else if (terminal.type === 'OpenNodeTag' && terminal.value.flags.intrinsic) {
+      printed += terminal.value.intrinsicValue;
+    }
+  }
+
+  return printed;
+};
+
+export function* generateSourceTextFor(terminals) {
+  for (const terminal of terminals) {
+    if (terminal.type === 'Literal') {
+      yield* terminal.value;
+    } else if (terminal.type === 'OpenNodeTag' && terminal.value.flags.intrinsic) {
+      yield* terminal.value.intrinsicValue;
+    }
+  }
+}
+
+export function sourceTextFor(terminals) {
+  return [...generateSourceTextFor(terminals)].join('');
+}
+
+export const startsDocument = (terminal) => {
+  const { type } = terminal;
+  if (type === 'OpenFragmentTag' || type === 'DoctypeTag') {
+    return true;
+  } else if (type === 'OpenNodeTag') {
+    const { flags } = terminal.value;
+
+    return flags.trivia || flags.escape;
+  }
+};

package/lib/template.js

@@ -0,0 +1,54 @@
+import * as t from './builders.js';
+
+const { isArray } = Array;
+const { freeze } = Object;
+
+export const interpolateArray = (value) => {
+  if (isArray(value)) {
+    return value;
+  } else {
+    return [value];
+  }
+};
+
+export const interpolateArrayChildren = (value, ref, sep) => {
+  if (isArray(value)) {
+    const values = value;
+    const children = [];
+    let first = true;
+    for (const _ of values) {
+      if (!first) children.push(freeze({ ...sep }));
+      children.push(freeze({ ...ref }));
+      first = false;
+    }
+    return children;
+  } else {
+    return [freeze({ ...ref })];
+  }
+};
+
+const validateTerminal = (term) => {
+  if (!term || (term.type !== 'Literal' && term.type !== 'Embedded')) {
+    throw new Error('Invalid terminal');
+  }
+  if (term.type === 'Embedded' && !term.value.flags.escape) {
+    throw new Error();
+  }
+};
+
+export const interpolateString = (value) => {
+  const terminals = [];
+  if (isArray(value)) {
+    for (const element of value) {
+      validateTerminal(element);
+
+      terminals.push(element);
+    }
+  } else {
+    // we can't safely interpolate strings here, though I wish we could
+    validateTerminal(value);
+    terminals.push(value);
+  }
+
+  return t.buildNode('String', 'Content', terminals);
+};

package/lib/tree.js

@@ -0,0 +1,373 @@
+import emptyStack from '@iter-tools/imm-stack';
+import {
+  buildNodeCloseTag,
+  buildNodeOpenTag,
+  buildNull,
+  buildEmbedded,
+  nodeFlags,
+  buildDoctypeTag,
+  buildFragmentOpenTag,
+  buildFragmentCloseTag,
+  buildReference,
+} from './builders.js';
+import {
+  printPrettyCSTML as printPrettyCSTMLFromStream,
+  printCSTML as printCSTMLFromStream,
+} from './stream.js';
+export * from './builders.js';
+export * from './print.js';
+
+const arrayLast = (arr) => arr[arr.length - 1];
+
+const buildFrame = (node) => {
+  if (!node) throw new Error();
+  return { node, childrenIdx: -1, resolver: new Resolver(node) };
+};
+
+const { hasOwn, freeze } = Object;
+
+const get = (node, path) => {
+  const { 1: name, 2: index } = /^([^\.]+)(?:\.(\d+))?/.exec(path) || [];
+
+  if (index != null) {
+    return node.properties[name]?.[parseInt(index, 10)];
+  } else {
+    return node.properties[name];
+  }
+};
+
+const reduceTokenToNodes = (nodes, token) => {
+  switch (token.type) {
+    case 'OpenFragmentTag':
+    case 'Null': {
+      return nodes;
+    }
+
+    case 'DoctypeTag': {
+      const { attributes } = token.value;
+
+      return nodes.push(
+        freeze({
+          flags: nodeFlags,
+          type: Symbol.for('@bablr/fragment'),
+          children: [],
+          properties: {},
+          attributes: freeze(attributes),
+        }),
+      );
+    }
+
+    case 'CloseFragmentTag': {
+      freeze(nodes.value.properties);
+      freeze(nodes.value.children);
+
+      return nodes.pop();
+    }
+
+    case 'Literal':
+    case 'Gap':
+    case 'Reference': {
+      nodes.value.children.push(token);
+      return nodes;
+    }
+
+    case 'OpenNodeTag': {
+      const buildStringTerminals = (str) => {
+        // do better
+        return [{ type: 'Literal', value: str }];
+      };
+
+      const { flags, language, type, intrinsicValue, attributes } = token.value;
+      const node = nodes.value;
+      const newNode = freeze({
+        flags,
+        language,
+        type,
+        children: flags.intrinsic ? buildStringTerminals(intrinsicValue) : [],
+        properties: {},
+        attributes: freeze(attributes),
+      });
+
+      if (node && !(flags.escape || flags.trivia)) {
+        if (nodes.size === 1) {
+          node.children.push(buildReference('root', false));
+        }
+
+        if (!node.children.length) {
+          throw new Error('Nodes must follow references');
+        }
+
+        const { name, isArray } = arrayLast(node.children).value;
+
+        if (isArray) {
+          if (!hasOwn(node.properties, name)) {
+            node.properties[name] = [];
+          }
+          const array = node.properties[name];
+
+          array.push(newNode);
+        } else {
+          node.properties[name] = newNode;
+        }
+      }
+
+      if (flags.intrinsic) {
+        freeze(newNode.children);
+        freeze(newNode.properties);
+        return nodes;
+      }
+
+      return nodes.push(newNode);
+    }
+
+    case 'CloseNodeTag': {
+      const completedNode = nodes.value;
+      const { flags } = completedNode;
+
+      if (flags.escape || flags.trivia) {
+        const parentChildren = nodes.prev.value.children;
+
+        parentChildren.push(buildEmbedded(completedNode));
+      }
+
+      freeze(completedNode.properties);
+      freeze(completedNode.children);
+
+      return nodes.pop();
+    }
+
+    default: {
+      throw new Error();
+    }
+  }
+};
+
+export const treeFromStreamSync = (tokens) => {
+  let nodes = emptyStack;
+  let rootNode;
+
+  for (const token of tokens) {
+    nodes = reduceTokenToNodes(nodes, token);
+    rootNode = nodes.value || rootNode;
+  }
+
+  return rootNode;
+};
+
+export const treeFromStreamAsync = async (tokens) => {
+  let nodes = emptyStack;
+  let rootNode;
+
+  for await (const token of tokens) {
+    nodes = reduceTokenToNodes(nodes, token);
+    rootNode = nodes.value || rootNode;
+  }
+
+  return rootNode;
+};
+
+export function* streamFromTree(rootNode) {
+  if (!rootNode || rootNode.type === 'Gap') {
+    return rootNode;
+  }
+
+  yield buildDoctypeTag(rootNode.attributes);
+  yield buildFragmentOpenTag();
+
+  let stack = emptyStack.push(buildFrame(rootNode));
+
+  stack: while (stack.size) {
+    const frame = stack.value;
+    const { node, resolver } = frame;
+    const { flags, language, type, children, attributes } = node;
+
+    const intrinsicValue = flags.intrinsic ? children[0].value : null;
+
+    if (frame.childrenIdx === -1 && stack.size > 1) {
+      yield buildNodeOpenTag(flags, language, type, intrinsicValue, attributes);
+    }
+
+    if (!flags.intrinsic) {
+      while (++frame.childrenIdx < node.children.length) {
+        const terminal = node.children[frame.childrenIdx];
+
+        switch (terminal.type) {
+          case 'Literal':
+          case 'Gap':
+          case 'Null': {
+            yield terminal;
+            break;
+          }
+
+          case 'Embedded': {
+            stack = stack.push(buildFrame(terminal.value));
+            continue stack;
+          }
+
+          case 'Reference': {
+            if (stack.size > 1) {
+              yield terminal;
+            }
+
+            const resolved = resolver.consume(terminal).get(terminal);
+            if (resolved) {
+              stack = stack.push(buildFrame(resolved));
+              continue stack;
+            } else {
+              yield buildNull();
+              break;
+            }
+          }
+
+          default: {
+            throw new Error();
+          }
+        }
+      }
+
+      if (stack.size > 1) {
+        yield buildNodeCloseTag(type, language);
+      }
+    }
+
+    stack = stack.pop();
+  }
+  yield buildFragmentCloseTag();
+}
+
+export const getCooked = (cookable) => {
+  if (!cookable || cookable.type === 'Gap') {
+    return '';
+  }
+
+  const children = cookable.children || cookable;
+
+  let cooked = '';
+
+  for (const terminal of children) {
+    switch (terminal.type) {
+      case 'Reference': {
+        throw new Error('cookable nodes must not contain other nodes');
+      }
+
+      case 'Embedded': {
+        const { flags, attributes } = terminal.value;
+
+        if (!(flags.trivia || (flags.escape && attributes.cooked))) {
+          throw new Error('cookable nodes must not contain other nodes');
+        }
+
+        if (flags.escape) {
+          const { cooked: cookedValue } = attributes;
+
+          if (!cookedValue) throw new Error('cannot cook string: it contains uncooked escapes');
+
+          cooked += cookedValue;
+        }
+
+        break;
+      }
+
+      case 'Literal': {
+        cooked += terminal.value;
+        break;
+      }
+
+      default: {
+        throw new Error();
+      }
+    }
+  }
+
+  return cooked;
+};
+
+export const printCSTML = (rootNode) => {
+  return printCSTMLFromStream(streamFromTree(rootNode));
+};
+
+export const printPrettyCSTML = (rootNode, indent = '  ') => {
+  return printPrettyCSTMLFromStream(streamFromTree(rootNode), indent);
+};
+
+export const printSource = (node) => {
+  const resolver = new Resolver(node);
+  let printed = '';
+
+  if (node instanceof Promise) {
+    printed += '$Promise';
+  } else {
+    for (const child of node.children) {
+      if (child.type === 'Literal') {
+        printed += child.value;
+      } else if (child.type === 'Embedded') {
+        printed += printSource(child.value);
+      } else if (child.type === 'Reference') {
+        const node_ = resolver.consume(child).get(child);
+
+        if (node_ || !child.value.isArray) {
+          printed += printSource(node_);
+        }
+      }
+    }
+  }
+
+  return printed;
+};
+
+export class Resolver {
+  constructor(node, counters = new Map()) {
+    this.node = node;
+    this.counters = counters;
+  }
+
+  consume(reference) {
+    const { name, isArray } = reference.value;
+    const { counters } = this;
+
+    if (isArray) {
+      const count = counters.get(name) + 1 || 0;
+
+      counters.set(name, count);
+    } else {
+      if (counters.has(name))
+        throw new Error(`attempted to consume property {name: ${name}} twice`);
+
+      counters.set(name, 1);
+    }
+
+    return this;
+  }
+
+  resolve(reference) {
+    let { name, isArray } = reference.value;
+    const { counters } = this;
+    let path = name;
+
+    if (isArray) {
+      const count = counters.get(name) || 0;
+
+      path += '.' + count;
+    }
+
+    return path;
+  }
+
+  get(reference) {
+    if (!this.node) throw new Error('Cannot get from a resolver with no node');
+
+    return get(this.node, this.resolve(reference));
+  }
+
+  branch() {
+    return new Resolver(this.node, new Map(this.counters));
+  }
+
+  accept(resolver) {
+    this.counters = resolver.counters;
+
+    return this;
+  }
+}
+
+freeze(Resolver.prototype);

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@bablr/agast-helpers",
+  "description": "Helper functions for working with agAST trees",
+  "version": "0.1.0",
+  "author": "Conrad Buck<conartist6@gmail.com>",
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "exports": {
+    "./builders": "./lib/builders.js",
+    "./path": "./lib/path.js",
+    "./print": "./lib/print.js",
+    "./shorthand": "./lib/shorthand.js",
+    "./stream": "./lib/stream.js",
+    "./template": "./lib/template.js",
+    "./tree": "./lib/tree.js"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@iter-tools/imm-stack": "1.1.0"
+  },
+  "devDependencies": {
+    "@bablr/eslint-config-base": "github:bablr-lang/eslint-config-base#d834ccc52795d6c3b96ecc6c419960fceed221a6",
+    "enhanced-resolve": "^5.12.0",
+    "eslint": "^8.32.0",
+    "eslint-import-resolver-enhanced-resolve": "^1.0.5",
+    "eslint-plugin-import": "^2.27.5",
+    "prettier": "^2.6.2"
+  },
+  "repository": "github:bablr-lang/agast-helpers",
+  "homepage": "https://github.com/bablr-lang/agast-helpers",
+  "license": "MIT"
+}