add types for writer

Author: saschanaz

lib/error.js

@@ -1,3 +1,5 @@
+/** @import { Base } from "./productions/base.js" */
+
 /**
  * @param {string} text
  */
@@ -14,6 +16,9 @@ function appendIfExist(base, target) {
   return result;
 }
 
+/**
+ * @param {Base} node
+ */
 function contextAsText(node) {
   const hierarchy = [node];
   while (node && node.parent) {

lib/productions/base.js

@@ -29,6 +29,9 @@ export class Base {
     });
   }
 
+  get type() { return undefined; };
+  get name() { return undefined; };
+
   /**
    * @param {Definitions} defs
    * @returns {IterableIterator<any>}
@@ -37,11 +40,12 @@ export class Base {
   *validate(defs) {}
 
   /**
-   * @param {Writer} w
-   * @returns {*}
+   * @template T
+   * @param {Writer<T>} w
+   * @returns {T | string}
    */
   // eslint-disable-next-line no-unused-vars
-  write(w) {}
+  write(w) { return "" }
 
   toJSON() {
     const json = { type: undefined, name: undefined, inheritance: undefined };

lib/writer.js

@@ -1,8 +1,39 @@
+/** @import { Base } from "./productions/base.js" */
+/** @import { Token } from "./tokeniser.js" */
+
+/**
+ * @template T
+ * @param {T} arg
+ */
 function noop(arg) {
   return arg;
 }
 
+/**
+ * @typedef {object} TemplateContext
+ * @property {Base} data
+ * @property {Base} parent
+ */
+
+/**
+ * @template T
+ * @typedef {object} WriteTemplates
+ * @property {(items: (T | string)[]) => T} wrap
+ * @property {(trivia: string) => T} trivia
+ * @property {(escaped: string, context: TemplateContext) => T} name
+ * @property {(escaped: string, unescaped: string, context: Base) => T} reference
+ * @property {(type: T) => T} type
+ * @property {(name: string) => T} generic
+ * @property {(keyword: string, context: TemplateContext) => T} nameless
+ * @property {(inheritable: T) => T} inheritance
+ * @property {(content: T, context: TemplateContext) => T} definition
+ * @property {(content: T) => T} extendedAttribute
+ * @property {(content: string) => T} extendedAttributeReference
+ */
+
+/** @type {WriteTemplates<string>} */
 const templates = {
+  /** @type {(items: any[]) => string} */
   wrap: (items) => items.join(""),
   trivia: noop,
   name: noop,
@@ -16,7 +47,14 @@ const templates = {
   extendedAttributeReference: noop,
 };
 
+/** @template T */
 export class Writer {
+  /** @type {WriteTemplates<T>} */
+  ts;
+
+  /**
+   * @param {WriteTemplates<T>} ts
+   */
   constructor(ts) {
     this.ts = Object.assign({}, templates, ts);
   }
@@ -25,8 +63,7 @@ export class Writer {
    * @param {string} raw
    * @param {object} options
    * @param {string} [options.unescaped]
-   * @param {import("./productions/base.js").Base} [options.context]
-   * @returns
+   * @param {Base} [options.context]
    */
   reference(raw, { unescaped, context }) {
     if (!unescaped) {
@@ -36,16 +73,30 @@ export class Writer {
   }
 
   /**
-   * @param {import("./tokeniser.js").Token} t
-   * @param {Function} wrapper
-   * @param {...any} args
-   * @returns
+   * @overload
+   * @param {Token} t
+   * @param {(tokenValue: string, options: { context: Base }) => T | string} wrapper
+   * @param {object} options
+   * @param {Base} options.context
+   * @returns {T | string}
+   */
+  /**
+   * @overload
+   * @param {Token} t
+   * @param {(tokenValue: string, context: TemplateContext) => T | string} [wrapper]
+   * @param {TemplateContext} [context]
+   * @returns {T | string}
+   */
+  /**
+   * @param {Token} t
+   * @param {(tokenValue: string, context: any) => T | string} [wrapper]
+   * @param {any} [context]
    */
-  token(t, wrapper = noop, ...args) {
+  token(t, wrapper = noop, context) {
     if (!t) {
       return "";
     }
-    const value = wrapper(t.value, ...args);
+    const value = wrapper(t.value, context);
     return this.ts.wrap([this.ts.trivia(t.trivia), value]);
   }
 
@@ -65,9 +116,29 @@ export class Writer {
   }
 }
 
+/**
+ * @overload
+ * @param {Base[]} ast
+ * @returns {string}
+ */
+/**
+ * @template T
+ * @overload
+ * @param {Base[]} ast
+ * @param {object} options
+ * @param {WriteTemplates<T>} [options.templates]
+ * @returns {T}
+ */
+/**
+ * @param {Base[]} ast
+ * @param {object} options
+ * @param {WriteTemplates<unknown>} [options.templates]
+ * @returns {unknown}
+ */
 export function write(ast, { templates: ts = templates } = {}) {
   ts = Object.assign({}, templates, ts);
 
+  /** @type {Writer<unknown>} */
   const w = new Writer(ts);
 
   return ts.wrap(ast.map((it) => it.write(w)));