@funcstache/stache-stream 0.2.2 → 0.2.3

package/src/lib/tag/Tag.ts

@@ -0,0 +1,295 @@
+import {
+  ContentTagTagTypes,
+  ContentTagTypes,
+  Tag as TagType,
+  ValueTagTagTypes,
+  ValueTagTypes,
+} from "../types";
+
+export class Tag implements TagType {
+  #content: string;
+  #dynamic: boolean | undefined;
+  #raw: boolean | undefined;
+  #rawBraces: boolean | undefined;
+  #type: ValueTagTagTypes | ContentTagTagTypes | undefined;
+  #value: string;
+
+  constructor(options: TagOptions) {
+    if (!options.value) {
+      throw StacheStreamError("`options.value` must contain a string value.");
+    }
+
+    this.#content = options.content || "";
+    this.#value = options.value;
+
+    if (options.rawBraces === true) {
+      this.#rawBraces = options.rawBraces;
+    }
+  }
+
+  get content() {
+    if ((ValueTagTypes as readonly string[]).includes(this.type)) {
+      return null;
+    }
+
+    return this.#content;
+  }
+
+  get dynamic(): boolean {
+    return this.#dynamic === undefined ? false : this.#dynamic;
+  }
+
+  /** This should match a key in the Context associated with the template. */
+  get key(): string {
+    return this.#tagName();
+  }
+
+  get raw(): boolean {
+    if (this.#raw === undefined) {
+      this.#extractValueInformation();
+
+      if (this.#raw === undefined) {
+        throw StacheStreamError(
+          "Failed to extract tag raw information from the tag value."
+        );
+      }
+    }
+
+    return this.#raw;
+  }
+
+  get type(): ValueTagTagTypes | ContentTagTagTypes {
+    if (!this.#type) {
+      this.#extractValueInformation();
+
+      if (!this.#type) {
+        throw StacheStreamError(
+          "Failed to extract tag type information from the tag value."
+        );
+      }
+    }
+
+    return this.#type;
+  }
+
+  get value(): string {
+    return this.#normalizedTagValue();
+  }
+
+  /** The `value` passed to the constructor via the `option` parameter. Only really useful for
+   * logging; prefer the `Tag.value` property. */
+  get valueOption(): string {
+    return this.#value;
+  }
+
+  static copy(
+    tag: Tag,
+    options?: Partial<Omit<TagOptions, "value"> & { key?: string }>
+  ): Tag {
+    const { key, ...restOptions } = options || {};
+
+    const allOptions: TagOptions = {
+      content: tag.#content,
+      rawBraces: tag.#rawBraces,
+      value: tag.#value,
+      ...restOptions,
+    };
+
+    let nextTag = new Tag(allOptions);
+
+    if (key) {
+      const nextValue = nextTag.#value.replace(nextTag.#tagName(), key);
+      nextTag = new Tag({ ...allOptions, value: nextValue });
+    }
+
+    return nextTag;
+  }
+
+  static parse(
+    tag: string,
+    tokens: [enter: string, exit: string] = ["{", "}"]
+  ): Tag | undefined {
+    let enterTokenCount = 0;
+    for (let i = 0; i < tag.length; i++) {
+      if (tag[i] !== tokens[0]) {
+        break;
+      }
+
+      enterTokenCount++;
+    }
+
+    if (enterTokenCount < 2) {
+      return;
+    }
+
+    enterTokenCount = enterTokenCount <= 3 ? enterTokenCount : 3;
+    const tagRight = tag.substring(enterTokenCount);
+
+    let exitTokenCount = 0;
+    for (let i = tagRight.length - 1; 0 <= i; i--) {
+      if (tagRight[i] !== tokens[1]) {
+        break;
+      }
+
+      exitTokenCount++;
+    }
+
+    if (exitTokenCount < enterTokenCount) {
+      return;
+    }
+
+    exitTokenCount =
+      enterTokenCount < exitTokenCount ? enterTokenCount : exitTokenCount;
+
+    const value = tagRight.substring(0, tagRight.length - exitTokenCount);
+
+    if (!value) {
+      return;
+    }
+
+    // console.log(
+    //   `---\nTag.parse:\n   enterTokenCount=${enterTokenCount}\n   exitTokenCount=${exitTokenCount}\n   value='${value}'`
+    // );
+
+    try {
+      return new Tag({
+        value,
+        rawBraces: enterTokenCount === 3,
+      });
+    } catch {
+      return;
+    }
+  }
+
+  appendContent(text: string): void {
+    if (!(ContentTagTypes as readonly string[]).includes(this.type)) {
+      return;
+    }
+
+    this.#content = (this.#content || "") + text;
+  }
+
+  toJSON(): string {
+    return this.toString();
+  }
+
+  toString(): string {
+    return `${this.#rawBraces ? "{{{" : "{{"}${this.#value}${
+      this.#rawBraces ? "}}}" : "}}"
+    }`;
+  }
+
+  #extractValueInformation(): void {
+    if (this.#rawBraces) {
+      this.#raw = true;
+      this.#type = this.value === "." ? "implicit" : "variable";
+      return;
+    }
+
+    let dynamic = false;
+    let raw = false;
+    let tagType: ValueTagTagTypes | ContentTagTagTypes = "variable";
+    const normalizedTagValue = this.value;
+    switch (normalizedTagValue[0]) {
+      case ".": {
+        tagType = "implicit";
+        break;
+      }
+      case ">": {
+        if (1 < normalizedTagValue.length && normalizedTagValue[1] === "*") {
+          throw Error(
+            `Dynamic partials are not implemented; tag value='${this.#value}'`
+          );
+          dynamic = true;
+        }
+        tagType = "partial";
+        break;
+      }
+      case "#": {
+        tagType = "section";
+        break;
+      }
+      case "/": {
+        tagType = "end";
+        break;
+      }
+      case "&": {
+        raw = true;
+        if (normalizedTagValue.slice(1) === ".") {
+          tagType = "implicit";
+        }
+        break;
+      }
+      case "^": {
+        tagType = "inverted";
+        break;
+      }
+      case "!": {
+        tagType = "comment";
+        break;
+      }
+      case "$": {
+        throw Error(`Blocks are not implemented; tag value='${this.#value}'`);
+        tagType = "block";
+        break;
+      }
+      case "<": {
+        if (1 < normalizedTagValue.length && normalizedTagValue[1] === "*") {
+          throw Error(
+            `Dynamic parents are not implemented; tag value='${this.#value}'`
+          );
+          dynamic = true;
+        }
+        throw Error(`Parents are not implemented; tag value='${this.#value}'`);
+        tagType = "parent";
+        break;
+      }
+    }
+
+    this.#dynamic = dynamic;
+    this.#raw = raw;
+    this.#type = tagType;
+  }
+
+  #normalizedTagValue(): string {
+    return this.#value.trim().replace(/\s/g, "");
+  }
+
+  #tagName(): string {
+    let val = this.#normalizedTagValue();
+    if (
+      val.startsWith("&") ||
+      val.startsWith(">") ||
+      val.startsWith("#") ||
+      val.startsWith("^") ||
+      val.startsWith("/") ||
+      val.startsWith("!") ||
+      val.startsWith("$") ||
+      val.startsWith("<")
+    ) {
+      val = val.substring(1);
+    }
+
+    if (val.startsWith("*")) {
+      val = val.substring(1);
+    }
+
+    if (val.endsWith("?")) {
+      val = val.slice(0, -1);
+    }
+
+    return val;
+  }
+}
+
+export interface TagAttributes {
+  dynamic?: boolean;
+  raw: boolean;
+  tagType?: ContentTagTagTypes | ValueTagTagTypes;
+}
+
+interface TagOptions {
+  rawBraces?: boolean;
+  content?: string;
+  value: string;
+}

package/src/lib/template/README.md

@@ -0,0 +1,102 @@
+# Template
+
+`Template` wires together `Parse`, `Tokenize`, and `Queue` to render a mustache template from a `ReadableStream<string>` against a data context. Rendered output is written incrementally to a caller-supplied `writeToOutput` function. When rendering is complete the `inactive` event is emitted.
+
+## How it works
+
+### Pipeline
+
+`read()` starts the internal `Parse → Tokenize → Queue` pipeline. Each layer feeds the next:
+
+1. `Parse` reads the stream character-by-character.
+2. `Tokenize` groups characters into text and tag tokens.
+3. `Queue` accumulates section/inverted tokens and dispatches all token types to `Template`'s handlers.
+
+The three pipeline objects are created lazily on first access via private getters.
+
+### Context lookup
+
+`getContextValue(tag)` resolves a tag's key against the current context. Keys may be dot-separated paths (e.g. `a.b.c`); each segment is resolved in turn. If the value at any intermediate key is a function (lambda), it is called and its return value is used as the context for remaining keys. If the key is not found in the local context, the lookup falls through to the parent `contextProvider` if one was supplied.
+
+### Token handlers
+
+Each token type dispatched by `Queue` has a dedicated private handler:
+
+| Token type | Handler           | Behaviour                                                                                                                                                                                                                                               |
+| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `text`     | `#handleText`     | Writes plain text to output, buffering trailing whitespace to support standalone tag detection.                                                                                                                                                         |
+| `variable` | `#handleVariable` | Resolves the tag key to a primitive value (calling a lambda if needed) and writes it HTML-escaped, or unescaped for triple-stache `{{{` tags.                                                                                                           |
+| `implicit` | `#handleImplicit` | Writes the current context value directly when it is a primitive (used inside sections iterating scalar arrays).                                                                                                                                        |
+| `section`  | `#handleSection`  | Skips when the context value is falsy/empty. For a lambda, calls it with the raw section string. Otherwise iterates over the context value (or wraps a single object in an array) and renders the section template in a child `Template` for each item. |
+| `inverted` | `#handleInverted` | Renders the section content only when the context value is falsy or an empty array.                                                                                                                                                                     |
+| `partial`  | `#handlePartial`  | Calls the context lambda to obtain a `ReadableStream` and optional context for the partial template, then renders it in a child `Template`. Standalone partials are indented and their trailing newline is consumed.                                    |
+| `inactive` | `#handleInactive` | Flushes any remaining pending whitespace then emits `inactive`.                                                                                                                                                                                         |
+
+### Whitespace and standalone tags
+
+Text tokens are not written immediately when they contain only horizontal whitespace (spaces and tabs). Instead, trailing whitespace is held in `#pendingWhitespace` until the next non-whitespace event. This lets `Template` detect standalone tags — tags that are the only non-whitespace content on a line — and suppress the surrounding indentation/newline for those tags as required by the mustache spec.
+
+### Sections and partials
+
+Both sections and partials are rendered by spawning a child `Template` instance. The child receives:
+
+- a `ReadableStream` containing the inner template string,
+- a `ContextProvider` whose `context` is the iteration item (sections) or partial-supplied context (partials),
+- the same `writeToOutput` function as the parent (partials may wrap it with `makeIndentingWriter` to apply per-line indentation).
+
+The parent `await`s the child's `inactive` event before continuing.
+
+## Usage
+
+```ts
+import { Template } from "./Template";
+
+let output = "";
+
+const template = new Template({
+  readable: myReadableStream,
+  contextProvider: {
+    context: { name: "world" },
+  },
+  writeToOutput: async (text) => {
+    output += text;
+  },
+});
+
+template.on("inactive", () => console.log(output));
+template.read();
+```
+
+## API
+
+### `new Template(options)`
+
+| Option            | Type                         | Description                                                    |
+| ----------------- | ---------------------------- | -------------------------------------------------------------- |
+| `readable`        | `ReadableStream<string>`     | The mustache template source.                                  |
+| `writeToOutput`   | `WriteToOutput`              | Called incrementally with rendered output chunks.              |
+| `contextProvider` | `ContextProvider` (optional) | Supplies the data context and parent lookup for this template. |
+
+Also accepts all `EventEmitter` constructor options.
+
+### `template.on(eventName, listener)`
+
+Inherited from `EventEmitter`. Registers a listener for a template event.
+
+### `template.read(): Template`
+
+Starts the rendering pipeline. Returns `this` for chaining. Listen for `inactive` to know when rendering is complete.
+
+### `template.getContextValue(tag): Promise<CTX | undefined>`
+
+Resolves a tag's key against the current context, following dot-separated paths and invoking lambdas as needed. Falls through to the parent `contextProvider` when the key is not found locally. Implements `ContextProvider`.
+
+### `template.context`
+
+Read-only. Returns the current context from the `contextProvider`, or `{}` if none was supplied.
+
+### Events
+
+| Event      | Payload     | Description                                                                 |
+| ---------- | ----------- | --------------------------------------------------------------------------- |
+| `inactive` | `undefined` | Emitted after all tokens have been rendered and pending whitespace flushed. |

package/src/lib/template/Template-comment.spec.ts

@@ -0,0 +1,76 @@
+import { TextDecoderStream } from "node:stream/web";
+import type { ContextTypes } from "../types";
+import { createReadableStream } from "../test/streams";
+import { Template } from "./Template";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(process.env as any).LOG_LEVEL = "warn";
+
+describe("Template comments", () => {
+  async function render(
+    template: string,
+    context?: ContextTypes
+  ): Promise<string[]> {
+    return new Promise<string[]>((resolve) => {
+      const calls: string[] = [];
+      new Template({
+        contextProvider: context !== undefined ? { context } : undefined,
+        readable: createReadableStream(template).pipeThrough(
+          new TextDecoderStream()
+        ),
+        writeToOutput: async (text) => {
+          calls.push(text);
+        },
+      })
+        .on("inactive", () => resolve(calls))
+        .read();
+    });
+  }
+
+  it("produces no output for a basic comment", async () => {
+    expect(await render("{{! comment }}")).toEqual([]);
+  });
+
+  it("strips an inline comment leaving surrounding text intact", async () => {
+    expect(await render("before{{! comment }}after")).toEqual([
+      "before",
+      "after",
+    ]);
+  });
+
+  it("treats a comment with embedded newlines as a single token", async () => {
+    expect(await render("{{! multi\nline }}")).toEqual([]);
+  });
+
+  it("suppresses the entire line for a standalone comment", async () => {
+    expect(await render("{{! comment }}\n")).toEqual([]);
+  });
+
+  it("suppresses leading whitespace for a standalone comment", async () => {
+    expect(await render("  {{! comment }}\n")).toEqual([]);
+  });
+
+  it("suppresses a standalone comment line in the middle of content", async () => {
+    expect((await render("before\n{{! comment }}\nafter")).join("")).toBe(
+      "before\nafter"
+    );
+  });
+
+  it("removes a non-standalone comment leaving surrounding line content", async () => {
+    expect((await render("text {{! comment }}\n")).join("")).toBe("text \n");
+  });
+
+  it("produces no output for a comment inside a section body", async () => {
+    expect(await render("{{#s}}{{! comment }}{{/s}}", { s: true })).toEqual([]);
+  });
+
+  it("suppresses a standalone comment line inside a section body", async () => {
+    expect(
+      (await render("{{#s}}\n{{! comment }}\n{{/s}}", { s: true })).join("")
+    ).toBe("");
+  });
+
+  it("treats a multi-line comment spanning source lines atomically", async () => {
+    expect(await render("{{!\n  I'm a comment\n}}")).toEqual([]);
+  });
+});

package/src/lib/template/Template-inverted-section.spec.ts

@@ -0,0 +1,85 @@
+import { TextDecoderStream } from "node:stream/web";
+import { Template } from "./Template";
+import { createReadableStream } from "../test/streams";
+import type { ContextTypes } from "../../types";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(process.env as any).LOG_LEVEL = "warn";
+
+describe("Template inverted sections", () => {
+  async function render(
+    template: string,
+    context: ContextTypes
+  ): Promise<string[]> {
+    return new Promise<string[]>((resolve) => {
+      const calls: string[] = [];
+      new Template({
+        contextProvider: { context },
+        readable: createReadableStream(template).pipeThrough(
+          new TextDecoderStream()
+        ),
+        writeToOutput: async (text) => {
+          calls.push(text);
+        },
+      })
+        .on("inactive", () => resolve(calls))
+        .read();
+    });
+  }
+
+  it("renders when context is false", async () => {
+    expect(await render("{{^s}}text{{/s}}", { s: false })).toEqual(["text"]);
+  });
+
+  it("renders nothing when context is true", async () => {
+    expect(await render("{{^s}}text{{/s}}", { s: true })).toEqual([]);
+  });
+
+  it("renders when key is absent from context", async () => {
+    expect(await render("{{^s}}text{{/s}}", {})).toEqual(["text"]);
+  });
+
+  it("renders when context is empty list", async () => {
+    expect(await render("{{^s}}text{{/s}}", { s: [] })).toEqual(["text"]);
+  });
+
+  it("renders when context is empty string", async () => {
+    expect(await render("{{^s}}text{{/s}}", { s: "" })).toEqual(["text"]);
+  });
+
+  it("renders nothing when context is a non-empty list", async () => {
+    expect(await render("{{^s}}text{{/s}}", { s: [1, 2] })).toEqual([]);
+  });
+
+  it("renders nothing when context is an object", async () => {
+    expect(await render("{{^s}}text{{/s}}", { s: {} })).toEqual([]);
+  });
+
+  it("resolves variables from parent context when rendered", async () => {
+    expect(
+      await render("{{^s}}{{name}}{{/s}}", { s: false, name: "Alice" })
+    ).toEqual(["Alice"]);
+  });
+
+  it("section renders but inverted does not when truthy", async () => {
+    expect(
+      await render("{{#a}}X{{/a}}{{^a}}Y{{/a}}", { a: true })
+    ).toEqual(["X"]);
+  });
+
+  it("inverted renders but section does not when falsy", async () => {
+    expect(
+      await render("{{#a}}X{{/a}}{{^a}}Y{{/a}}", { a: false })
+    ).toEqual(["Y"]);
+  });
+
+  describe("standalone suppression", () => {
+    it("suppresses standalone inverted section tag lines", async () => {
+      expect((await render("{{^s}}\nbody\n{{/s}}\n", { s: false })).join("")).toBe("body\n");
+    });
+
+    it("suppresses standalone inverted section in middle of content", async () => {
+      expect((await render("before\n{{^s}}\nbody\n{{/s}}\nafter", { s: false })).join("")).toBe("before\nbody\nafter");
+    });
+  });
+});

package/src/lib/template/Template-partials.spec.ts

@@ -0,0 +1,125 @@
+import { ReadableStream, TextDecoderStream } from "node:stream/web";
+import { Template } from "./Template";
+import { createReadableStream } from "../test/streams";
+import type { ContextTypes, PartialTagContextLambda } from "../types";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(process.env as any).LOG_LEVEL = "warn";
+
+describe("Template partials", () => {
+  function makePartial(
+    template: string,
+    context?: ContextTypes
+  ): PartialTagContextLambda {
+    return async () => ({
+      context,
+      input: async () =>
+        createReadableStream(template).pipeThrough(
+          new TextDecoderStream()
+        ) as ReadableStream,
+    });
+  }
+
+  async function render(
+    template: string,
+    context: ContextTypes
+  ): Promise<string[]> {
+    return new Promise<string[]>((resolve) => {
+      const calls: string[] = [];
+      new Template({
+        contextProvider: { context },
+        readable: createReadableStream(template).pipeThrough(
+          new TextDecoderStream()
+        ),
+        writeToOutput: async (text) => {
+          calls.push(text);
+        },
+      })
+        .on("inactive", () => resolve(calls))
+        .read();
+    });
+  }
+
+  it("renders a basic partial", async () => {
+    expect(await render("{{> p}}", { p: makePartial("hello") })).toEqual([
+      "hello",
+    ]);
+  });
+
+  it("renders partial inline with surrounding text", async () => {
+    expect(
+      await render("before {{> p}} after", { p: makePartial("mid") })
+    ).toEqual(["before ", "mid", " after"]);
+  });
+
+  it("produces no output for a missing partial", async () => {
+    expect(await render("{{> missing}}", {})).toEqual([]);
+  });
+
+  it("renders partial with lambda-provided context", async () => {
+    expect(
+      await render("{{> p}}", {
+        p: makePartial("{{name}}", { name: "Alice" }),
+      })
+    ).toEqual(["Alice"]);
+  });
+
+  it("partial inherits parent context when no lambda context provided", async () => {
+    expect(
+      await render("{{> p}}", { name: "Bob", p: makePartial("{{name}}") })
+    ).toEqual(["Bob"]);
+  });
+
+  it("renders partial once per section item", async () => {
+    expect(
+      await render("{{#items}}{{> p}}{{/items}}", {
+        items: [{ name: "A" }, { name: "B" }],
+        p: makePartial("{{name}}"),
+      })
+    ).toEqual(["A", "B"]);
+  });
+
+  it("renders recursively nested partials", async () => {
+    const inner = makePartial("hi");
+    const outer = makePartial("{{> inner}}", { inner });
+    expect(await render("{{> outer}}", { outer, inner })).toEqual(["hi"]);
+  });
+
+  it("applies indent to every line of a standalone partial", async () => {
+    const result = await render("  {{> p}}\n", {
+      p: makePartial("a\nb"),
+    });
+    expect(result.join("")).toBe("  a\n  b");
+  });
+
+  it("preserves trailing newline when indenting a standalone partial", async () => {
+    const result = await render("  {{> p}}\n", {
+      p: makePartial("line1\nline2\n"),
+    });
+    expect(result.join("")).toBe("  line1\n  line2\n");
+  });
+
+  it("does not add trailing whitespace to empty lines when indenting", async () => {
+    const result = await render("  {{> p}}\n", {
+      p: makePartial("before\n\nafter"),
+    });
+    expect(result.join("")).toBe("  before\n\n  after");
+  });
+
+  it("does not apply indent for a non-standalone partial", async () => {
+    const result = await render("text {{> p}}\n", {
+      p: makePartial("a\nb"),
+    });
+    expect(result.join("")).toBe("text a\nb\n");
+  });
+
+  it("partial inside section falls back through section context to root context", async () => {
+    expect(
+      await render("{{#s}}{{> p}}{{/s}}", {
+        name: "root",
+        s: {},
+        p: makePartial("{{name}}"),
+      })
+    ).toEqual(["root"]);
+  });
+});