@funcstache/stache-stream 0.2.2 → 0.2.3

package/src/lib/stache-stream/StacheStream.spec.ts

@@ -0,0 +1,107 @@
+import { ReadableStream, TextDecoderStream } from "node:stream/web";
+import type {
+  ContextProvider,
+  ContextTypes,
+  PartialTagContextLambda,
+} from "../types";
+import { createReadableStream } from "../test/streams";
+import { StacheTransformStream } from "./StacheStream";
+
+async function render(
+  template: string,
+  contextProvider?: ContextProvider
+): Promise<string[]> {
+  const readable = createReadableStream(template);
+  const stache = new StacheTransformStream({ contextProvider });
+  const transformed = readable
+    .pipeThrough(new TextDecoderStream())
+    .pipeThrough(stache);
+  const chunks: string[] = [];
+  for await (const chunk of transformed) {
+    chunks.push(chunk);
+  }
+  return chunks;
+}
+
+function makePartial(
+  template: string,
+  context?: ContextTypes
+): PartialTagContextLambda {
+  return async () => ({
+    context,
+    input: async () =>
+      createReadableStream(template).pipeThrough(
+        new TextDecoderStream()
+      ) as ReadableStream,
+  });
+}
+
+describe("StacheTransformStream", () => {
+  it("passes through plain text", async () => {
+    expect(await render("fubar")).toEqual(["fubar"]);
+  });
+
+  describe("variable", () => {
+    it("renders an escaped variable", async () => {
+      expect(
+        await render("Hi {{name}}!", { context: { name: "Alice" } })
+      ).toEqual(["Hi ", "Alice", "!"]);
+    });
+
+    it("HTML-escapes the value", async () => {
+      expect(await render("{{val}}", { context: { val: "a&b" } })).toEqual([
+        "a&amp;b",
+      ]);
+    });
+
+    it("renders a raw variable with triple braces", async () => {
+      expect(
+        await render("{{{html}}}", { context: { html: "<b>ok</b>" } })
+      ).toEqual(["<b>ok</b>"]);
+    });
+
+    it("renders a raw variable with ampersand", async () => {
+      expect(
+        await render("{{&html}}", { context: { html: "<b>ok</b>" } })
+      ).toEqual(["<b>ok</b>"]);
+    });
+  });
+
+  it("renders the implicit iterator", async () => {
+    expect(await render("{{.}}", { context: "hello" })).toEqual(["hello"]);
+  });
+
+  it("renders a partial", async () => {
+    expect(
+      await render("Hello, {{>p}}!", { context: { p: makePartial("world") } })
+    ).toEqual(["Hello, ", "world", "!"]);
+  });
+
+  describe("section", () => {
+    it("renders a truthy section", async () => {
+      expect(
+        await render("{{#show}}yes{{/show}}", { context: { show: true } })
+      ).toEqual(["yes"]);
+    });
+
+    it("skips a falsy section", async () => {
+      expect(
+        await render("{{#show}}yes{{/show}}", { context: { show: false } })
+      ).toEqual([]);
+    });
+
+    it("renders a dotted-name section", async () => {
+      expect(
+        await render("{{#a.b}}yes{{/a.b}}", { context: { a: { b: true } } })
+      ).toEqual(["yes"]);
+    });
+
+    it("iterates over a list", async () => {
+      expect(
+        await render("{{#items}}{{.}} {{/items}}", {
+          context: { items: ["a", "b"] },
+        })
+      ).toEqual(["a", " ", "b", " "]);
+    });
+  });
+});

package/src/lib/stache-stream/StacheStream.ts

@@ -0,0 +1,79 @@
+import { ReadableStream, TransformStream } from "node:stream/web";
+import type { ContextProvider } from "../types";
+import { Template } from "../template/Template";
+
+/**
+ * A {@link https://nodejs.org/api/webstreams.html#class-transformstream TransformStream} that
+ * renders a Mustache template.
+ *
+ * @remarks
+ * The incoming {@link https://nodejs.org/api/webstreams.html#class-readablestream ReadableStream}
+ * provides the contents of a Mustache template. The stream is processed by StacheStreamTransform
+ * which emits the rendered Mustache template. The information needed to render the template is made
+ * available through `options` by the `ContextProvider`.
+ */
+export class StacheTransformStream extends TransformStream<string, string> {
+  /**
+   * @param options Options needed to render a Mustache template stream.
+   * @param options.contextProvider The `ContextProvider` is used during the render process to
+   * access the context for tags.
+   */
+  constructor(options?: { contextProvider?: ContextProvider }) {
+    const { readable, push, close } = createReadableProducer<string>();
+
+    let resolveInactive!: () => void;
+    let rejectInactive!: (err: unknown) => void;
+    const waitInactive = new Promise<void>((resolve, reject) => {
+      resolveInactive = resolve;
+      rejectInactive = reject;
+    });
+
+    super({
+      start(controller) {
+        new Template({
+          contextProvider: options?.contextProvider,
+          readable,
+          writeToOutput: async (text: string) => {
+            try {
+              controller.enqueue(text);
+            } catch (err) {
+              rejectInactive(err);
+              throw err;
+            }
+          },
+        })
+          .on("inactive", () => resolveInactive())
+          .read();
+      },
+      transform(chunk) {
+        push(chunk);
+      },
+      async flush(controller) {
+        close();
+        try {
+          await waitInactive;
+        } catch (err) {
+          controller.error(err);
+        }
+      },
+    });
+  }
+}
+
+function createReadableProducer<T>(): {
+  readable: ReadableStream<T>;
+  push: (chunk: T) => void;
+  close: () => void;
+} {
+  let pushChunk!: (chunk: T) => void;
+  let closeStream!: () => void;
+
+  const readable = new ReadableStream<T>({
+    start(controller) {
+      pushChunk = controller.enqueue.bind(controller);
+      closeStream = controller.close.bind(controller);
+    },
+  });
+
+  return { readable, push: pushChunk, close: closeStream };
+}

package/src/lib/tag/README.md

@@ -0,0 +1,95 @@
+# Tag
+
+`Tag` parses a raw mustache tag string (e.g. `{{#section}}`) and exposes its type, key, and rendering properties. It is the data object emitted by `Tokenize` and consumed by `Queue` and `Template`.
+
+## How it works
+
+### Parsing
+
+`Tag.parse(tag)` is the primary entry point. It counts the leading brace characters to determine the delimiter width (2 for `{{`, 3 for `{{{`), strips the delimiters, and constructs a `Tag` from the inner value. Returns `undefined` if the string is not a valid tag (fewer than two opening braces, mismatched brace counts, or empty inner value).
+
+Triple-brace tags (`{{{value}}}`) set the `rawBraces` flag, which causes `raw` to return `true` without further inspection of the value prefix.
+
+### Type detection
+
+Tag type and `raw` flag are derived lazily from the first character of the normalized value (whitespace stripped, no surrounding braces):
+
+| First char        | Type                              | `raw`   |
+| ----------------- | --------------------------------- | ------- |
+| _(none / letter)_ | `variable`                        | `false` |
+| `.`               | `implicit`                        | `false` |
+| `>`               | `partial`                         | `false` |
+| `#`               | `section`                         | `false` |
+| `/`               | `end`                             | `false` |
+| `^`               | `inverted`                        | `false` |
+| `!`               | `comment`                         | `false` |
+| `&`               | `variable` (or `implicit` if `.`) | `true`  |
+| `{{{…}}}`         | `variable` (or `implicit` if `.`) | `true`  |
+
+### Key extraction
+
+`key` returns the lookup key used for context resolution. It strips any leading sigil (`>`, `#`, `/`, `^`, `&`, `!`, `$`, `<`) and any leading `*` (dynamic marker) or trailing `?`, then returns the remainder. For `{{name}}` the key is `name`; for `{{#list}}` the key is `list`.
+
+### Value normalization
+
+`value` trims whitespace and removes all internal whitespace from the raw constructor value. `toString()` / `toJSON()` reconstruct the original tag syntax including braces (`{{value}}` or `{{{value}}}`).
+
+### Content
+
+`content` holds text appended via `appendContent(text)`. It is only available for block-level tag types (`section`, `inverted`, `end`, `parent`, `block`); it returns `null` for value tag types (`variable`, `implicit`, `partial`, `comment`).
+
+### Copying
+
+`Tag.copy(tag, options)` creates a new `Tag` from an existing one, optionally overriding constructor options or replacing the `key` within the value string.
+
+## Usage
+
+```ts
+import { Tag } from "./Tag";
+
+const tag = Tag.parse("{{#items}}");
+// tag.type    → "section"
+// tag.key     → "items"
+// tag.raw     → false
+// tag.value   → "#items"
+// tag.toString() → "{{#items}}"
+
+const raw = Tag.parse("{{{html}}}");
+// raw.type  → "variable"
+// raw.key   → "html"
+// raw.raw   → true
+```
+
+## API
+
+### `Tag.parse(tag, tokens?): Tag | undefined`
+
+Parses a raw tag string and returns a `Tag`, or `undefined` if the string is not a valid tag. `tokens` defaults to `["{", "}"]`.
+
+### `Tag.copy(tag, options?): Tag`
+
+Creates a copy of `tag`. Pass `options` to override `content`, `rawBraces`, or `key` (replaces the key within the value string).
+
+### `new Tag(options)`
+
+| Option      | Type                 | Description                                                  |
+| ----------- | -------------------- | ------------------------------------------------------------ |
+| `value`     | `string`             | The inner tag string (without surrounding braces). Required. |
+| `content`   | `string` (optional)  | Initial content for block-level tags.                        |
+| `rawBraces` | `boolean` (optional) | Set `true` for triple-brace tags.                            |
+
+### `tag.appendContent(text): void`
+
+Appends `text` to `content`. No-op for value tag types.
+
+### Properties
+
+| Property      | Type                                     | Description                                                               |
+| ------------- | ---------------------------------------- | ------------------------------------------------------------------------- |
+| `type`        | `ValueTagTagTypes \| ContentTagTagTypes` | The tag type derived from the value prefix.                               |
+| `key`         | `string`                                 | The context lookup key (sigil and dynamic markers stripped).              |
+| `raw`         | `boolean`                                | `true` for `{{{…}}}` or `{{&…}}` tags; output should not be HTML-escaped. |
+| `value`       | `string`                                 | Normalised tag value (whitespace removed, no braces).                     |
+| `content`     | `string \| null`                         | Accumulated inner content for block-level tags; `null` for value tags.    |
+| `dynamic`     | `boolean`                                | `true` for dynamic partial/parent tags (not yet implemented).             |
+| `valueOption` | `string`                                 | The raw value string passed to the constructor, before normalisation.     |

package/src/lib/tag/Tag.spec.ts

@@ -0,0 +1,212 @@
+import { Tag } from "./Tag";
+
+describe("Tag: properties from value", () => {
+  it("throws if an empty string is passed to the constructor", () => {
+    expect(() => new Tag({ value: "" })).toThrowError(
+      "`options.value` must contain a string value."
+    );
+  });
+
+  it("normalizes a tag value with a preceding operator", () => {
+    const tag = new Tag({
+      value: " > A ",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("A");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("partial");
+    expect(tag.value).toBe(">A");
+  });
+
+  it("normalizes a tag value with a non-false operator", () => {
+    const tag = new Tag({
+      value: " #Z  ? ",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("Z");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("section");
+    expect(tag.value).toBe("#Z?");
+  });
+
+  it("normalizes an implicit tag value", () => {
+    const tag = new Tag({ value: " . " });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe(".");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("implicit");
+    expect(tag.value).toBe(".");
+  });
+
+  it("variable", () => {
+    const tag = new Tag({ value: "a" });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("a");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("variable");
+    expect(tag.value).toBe("a");
+  });
+
+  it("implicit", () => {
+    const tag = new Tag({ value: "." });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe(".");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("implicit");
+    expect(tag.value).toBe(".");
+  });
+
+  it("triple braces raw implicit", () => {
+    const tag = new Tag({
+      rawBraces: true,
+      value: ".",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe(".");
+    expect(tag.raw).toBe(true);
+    expect(tag.type).toBe("implicit");
+    expect(tag.value).toBe(".");
+  });
+
+  it("triple braces raw variable", () => {
+    const tag = new Tag({ rawBraces: true, value: "name" });
+    expect(tag.raw).toBe(true);
+    expect(tag.type).toBe("variable");
+  });
+
+  it("partial", () => {
+    const tag = new Tag({ value: "> p" });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("p");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("partial");
+    expect(tag.value).toBe(">p");
+  });
+
+  it("section", () => {
+    const tag = new Tag({ value: " #s" });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("s");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("section");
+    expect(tag.value).toBe("#s");
+  });
+
+  it("end", () => {
+    const tag = new Tag({
+      value: " / E",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("E");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("end");
+    expect(tag.value).toBe("/E");
+  });
+
+  it("raw", () => {
+    const tag = new Tag({
+      value: " & r ",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("r");
+    expect(tag.raw).toBe(true);
+    expect(tag.type).toBe("variable");
+    expect(tag.value).toBe("&r");
+  });
+
+  it("inverted", () => {
+    const tag = new Tag({
+      value: " ^ iv ",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("iv");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("inverted");
+    expect(tag.value).toBe("^iv");
+  });
+
+  it("comment", () => {
+    const tag = new Tag({
+      value: " ! c ",
+    });
+    expect(tag.dynamic).toBe(false);
+    expect(tag.key).toBe("c");
+    expect(tag.raw).toBe(false);
+    expect(tag.type).toBe("comment");
+    expect(tag.value).toBe("!c");
+  });
+});
+
+describe("Tag: content", () => {
+  it("variable: default is null", () => {
+    const t = new Tag({
+      value: "name",
+    });
+    expect(t.type).toBe("variable");
+    expect(t.content).toBe(null);
+  });
+
+  it("variable: append has no effect", () => {
+    const t = new Tag({
+      value: "name",
+    });
+
+    t.appendContent("CONTENT");
+    expect(t.type).toBe("variable");
+    expect(t.content).toBe(null);
+  });
+
+  it("content: default is ''", () => {
+    const t = new Tag({
+      value: "#name",
+    });
+    expect(t.type).toBe("section");
+    expect(t.content).toBe("");
+  });
+
+  it("content: can append coontent", () => {
+    const t = new Tag({
+      value: "#name",
+    });
+    expect(t.type).toBe("section");
+    expect(t.content).toBe("");
+
+    t.appendContent("_CONTENT1");
+    expect(t.content).toBe("_CONTENT1");
+
+    t.appendContent("_CONTENT2");
+    expect(t.content).toBe("_CONTENT1_CONTENT2");
+  });
+});
+
+describe("Tag: context", () => {
+  it("gets context", () => {
+    const t = new Tag({
+      value: "name",
+    });
+  });
+});
+
+describe("implicit iterator", () => {
+  it("triple-brace {{{.}}} produces type implicit with raw true", () => {
+    const tag = Tag.parse("{{{.}}}");
+    expect(tag?.type).toBe("implicit");
+    expect(tag?.raw).toBe(true);
+    expect(tag?.key).toBe(".");
+  });
+
+  it("ampersand {{&.}} produces type implicit with raw true", () => {
+    const tag = Tag.parse("{{&.}}");
+    expect(tag?.type).toBe("implicit");
+    expect(tag?.raw).toBe(true);
+    expect(tag?.key).toBe(".");
+  });
+});
+
+describe("Tag.copy", () => {
+  it("copies a tag and replaces value", () => {
+    const tag = new Tag({ value: "> one.two ?" });
+    const copy = Tag.copy(tag, { key: "three" });
+    expect(copy.valueOption).toBe("> three ?");
+  });
+});