npm - @microsoft/fast-build - Versions diffs - 0.1.1 - Mend

@microsoft/fast-build 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +103 -0
package/bin/fast.js +255 -0
package/get-package-json.js +25 -0
package/package.json +36 -0
package/wasm/microsoft_fast_build.d.ts +24 -0
package/wasm/microsoft_fast_build.js +199 -0
package/wasm/microsoft_fast_build_bg.wasm +0 -0
package/wasm/microsoft_fast_build_bg.wasm.d.ts +12 -0

package/README.md ADDED Viewed

@@ -0,0 +1,103 @@
+# `@microsoft/fast-build`
+Server-side renderer for [FAST](https://www.fast.design/) declarative HTML templates, powered by a WebAssembly core with zero runtime npm dependencies.
+## Installation
+```sh
+npm install @microsoft/fast-build
+```
+## CLI usage
+Once installed, the `fast` binary is available. Use the `build` subcommand to render an HTML template with a JSON state file:
+```sh
+fast build [options]
+```
+### Options
+| Option | Default | Description |
+|---|---|---|
+| `--entry="<path>"` | `index.html` | Entry HTML template to render |
+| `--state="<path>"` | `state.json` | JSON file containing the template state |
+| `--output="<path>"` | `output.html` | Where to write the rendered HTML |
+| `--templates="<glob>"` | _(none)_ | Glob pattern(s) for custom element template HTML files. Separate multiple patterns with commas. A warning is printed if not provided or if no files match a pattern. |
+### Example
+Given an `index.html`:
+```html
+<html>
+  <body>
+    <h1>{{title}}</h1>
+    <p>{{description}}</p>
+  </body>
+</html>
+```
+And a `state.json`:
+```json
+{
+  "title": "Hello FAST",
+  "description": "Server-side rendered with WebAssembly."
+}
+```
+Run:
+```sh
+fast build --entry=index.html --state=state.json --output=output.html
+```
+Produces `output.html`:
+```html
+<html>
+  <body>
+    <h1>Hello FAST</h1>
+    <p>Server-side rendered with WebAssembly.</p>
+  </body>
+</html>
+```
+### Custom element templates
+Pass a glob pattern (or comma-separated list of patterns) to `--templates` to expand custom elements into [Declarative Shadow DOM](https://developer.chrome.com/docs/css-ui/declarative-shadow-dom):
+```sh
+fast build \
+  --templates="./components/**/*.html" \
+  --entry=index.html \
+  --state=state.json \
+  --output=output.html
+```
+Each matched `.html` file is scanned for `<f-template>` elements. The `name` attribute of each `<f-template>` determines the custom element name. A single file may contain multiple templates.
+Template files must use the following format:
+```html
+<f-template name="my-button">
+    <template>
+        <button>{{label}}</button>
+    </template>
+</f-template>
+```
+If an `<f-template>` element has no `name` attribute, a warning is printed and it is ignored. Exact file paths (no wildcards) are also accepted as patterns, making it possible to register a single template file.
+## Template syntax
+Template syntax follows the FAST declarative HTML format. See the [`@microsoft/fast-html` README](../fast-html/README.md) for full documentation on bindings, conditionals, repeats, and directives.
+## Contributing
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+## License
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

package/bin/fast.js ADDED Viewed

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// @ts-check
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const WASM_MODULE = path.join(__dirname, "../wasm/microsoft_fast_build.js");
+/**
+ * Parse CLI arguments of the form --key="value" or --key=value.
+ * @param {string[]} argv
+ * @returns {Record<string, string>}
+ */
+function parseArgs(argv) {
+    const args = {};
+    for (const arg of argv) {
+        const match = arg.match(/^--([^=]+)=(.*)$/s);
+        if (match) {
+            args[match[1]] = match[2].replace(/^"|"$/g, "");
+        }
+    }
+    return args;
+}
+/**
+ * Walk a directory recursively and collect all .html file paths.
+ * @param {string} dir
+ * @param {string[]} results
+ */
+function walkHtmlFiles(dir, results) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            walkHtmlFiles(fullPath, results);
+        } else if (entry.isFile() && entry.name.endsWith(".html")) {
+            results.push(fullPath);
+        }
+    }
+}
+/**
+ * Match a normalized path against a glob pattern.
+ * Supports * (within one segment), ** (across segments), ? (single char).
+ * @param {string} pattern
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function globMatch(pattern, filePath) {
+    const normalize = (p) => p.replace(/\\/g, "/").replace(/^\.\//, "");
+    const pat = normalize(pattern).split("/");
+    const file = normalize(filePath).split("/");
+    return matchSegments(pat, file);
+}
+/** @param {string[]} pat @param {string[]} file @returns {boolean} */
+function matchSegments(pat, file) {
+    if (pat.length === 0) return file.length === 0;
+    if (pat[0] === "**") {
+        if (matchSegments(pat.slice(1), file)) return true;
+        if (file.length > 0 && matchSegments(pat, file.slice(1))) return true;
+        return false;
+    }
+    if (file.length === 0) return false;
+    if (matchSegment(pat[0], file[0])) return matchSegments(pat.slice(1), file.slice(1));
+    return false;
+}
+/** @param {string} pat @param {string} seg @returns {boolean} */
+function matchSegment(pat, seg) {
+    return matchChars([...pat], [...seg]);
+}
+/** @param {string[]} pat @param {string[]} seg @returns {boolean} */
+function matchChars(pat, seg) {
+    if (pat.length === 0) return seg.length === 0;
+    if (pat[0] === "*") {
+        for (let i = 0; i <= seg.length; i++) {
+            if (matchChars(pat.slice(1), seg.slice(i))) return true;
+        }
+        return false;
+    }
+    if (seg.length === 0) return false;
+    if (pat[0] === "?" || pat[0] === seg[0]) return matchChars(pat.slice(1), seg.slice(1));
+    return false;
+}
+/**
+ * Given a glob pattern, return the static directory prefix before the first wildcard.
+ * @param {string} pattern
+ * @returns {string}
+ */
+function staticPrefixDir(pattern) {
+    const norm = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
+    const firstWild = norm.search(/[*?]/);
+    if (firstWild === -1) {
+        const lastSlash = norm.lastIndexOf("/");
+        return lastSlash >= 0 ? norm.slice(0, lastSlash + 1) : ".";
+    }
+    const before = norm.slice(0, firstWild);
+    const lastSlash = before.lastIndexOf("/");
+    return lastSlash >= 0 ? before.slice(0, lastSlash + 1) : ".";
+}
+/**
+ * Parse all `<f-template>` elements from an HTML string using the WASM module.
+ * Returns [{name, content}] for templates that have a `name` attribute.
+ * Emits a warning to stderr for any `<f-template>` without a `name`.
+ * @param {string} html
+ * @param {string} filePath - used in warning messages
+ * @param {object} wasm - the loaded WASM module
+ * @returns {{ name: string, content: string }[]}
+ */
+function parseFTemplates(html, filePath, wasm) {
+    /** @type {{ name: string | null, content: string }[]} */
+    const parsed = JSON.parse(wasm.parse_f_templates(html));
+    const results = [];
+    for (const { name, content } of parsed) {
+        if (name === null) {
+            process.stderr.write(
+                `Warning: <f-template> without a 'name' attribute in '${filePath}': ${content.trim()}\n`
+            );
+        } else {
+            results.push({ name, content });
+        }
+    }
+    return results;
+}
+/**
+ * Resolve all HTML files matching a glob pattern.
+ * Parses `<f-template name="...">` elements from each matched file and
+ * returns one entry per template. A single file may yield multiple entries.
+ * Warns (but does not error) if the base directory does not exist.
+ * @param {string} pattern
+ * @param {object} wasm - the loaded WASM module
+ * @returns {{ name: string, content: string }[]}
+ */
+function resolvePattern(pattern, wasm) {
+    const baseDir = staticPrefixDir(pattern);
+    if (!fs.existsSync(baseDir)) {
+        return [];
+    }
+    const allFiles = [];
+    walkHtmlFiles(baseDir, allFiles);
+    const results = [];
+    for (const file of allFiles) {
+        if (globMatch(pattern, file)) {
+            const html = fs.readFileSync(file, "utf8");
+            const templates = parseFTemplates(html, file, wasm);
+            for (const { name, content } of templates) {
+                results.push({ name, content });
+            }
+        }
+    }
+    return results;
+}
+async function runBuild(args) {
+    const templatesArg = args["templates"];
+    const output = args["output"] || "output.html";
+    const entry = args["entry"] || "index.html";
+    const stateFile = args["state"] || "state.json";
+    // Load WASM module first — needed for both template parsing and rendering.
+    const wasm = require(WASM_MODULE);
+    // Resolve template files
+    const templatesMap = {};
+    if (!templatesArg) {
+        process.stderr.write(
+            "Warning: --templates was not provided. No custom element templates will be loaded.\n"
+        );
+    } else {
+        const patterns = templatesArg.split(",").map((p) => p.trim());
+        for (const pattern of patterns) {
+            const matches = resolvePattern(pattern, wasm);
+            if (matches.length === 0) {
+                process.stderr.write(
+                    `Warning: No template files found for pattern "${pattern}".\n`
+                );
+            }
+            for (const { name, content } of matches) {
+                if (name in templatesMap) {
+                    process.stderr.write(
+                        `Warning: Duplicate template name "${name}" — later file overwrites earlier.\n`
+                    );
+                }
+                templatesMap[name] = content;
+            }
+        }
+    }
+    // Read entry file
+    if (!fs.existsSync(entry)) {
+        process.stderr.write(`Error: Entry file "${entry}" not found.\n`);
+        process.exit(1);
+    }
+    const entryContent = fs.readFileSync(entry, "utf8");
+    // Read state file
+    if (!fs.existsSync(stateFile)) {
+        process.stderr.write(`Error: State file "${stateFile}" not found.\n`);
+        process.exit(1);
+    }
+    const stateContent = fs.readFileSync(stateFile, "utf8");
+    // Render
+    let rendered;
+    if (Object.keys(templatesMap).length > 0) {
+        rendered = wasm.render_with_templates(entryContent, JSON.stringify(templatesMap), stateContent);
+    } else {
+        rendered = wasm.render(entryContent, stateContent);
+    }
+    // Write output
+    fs.writeFileSync(output, rendered, "utf8");
+    process.stdout.write(`Built: ${output}\n`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+        process.stdout.write(
+            "Usage: fast build [options]\n\n" +
+            "Options:\n" +
+            '  --templates="<glob>"   Glob pattern(s) for custom element template HTML files.\n' +
+            '                         Separate multiple patterns with commas.\n' +
+            '  --output="output.html" Output file path (default: output.html)\n' +
+            '  --entry="index.html"   Entry HTML template file (default: index.html)\n' +
+            '  --state="state.json"   State JSON file (default: state.json)\n'
+        );
+        return;
+    }
+    const subcommand = argv[0];
+    if (subcommand !== "build") {
+        process.stderr.write(`Unknown subcommand: "${subcommand}". Expected "build".\n`);
+        process.exit(1);
+    }
+    const args = parseArgs(argv.slice(1));
+    await runBuild(args);
+}
+main().catch((err) => {
+    process.stderr.write(`Error: ${err.message || err}\n`);
+    process.exit(1);
+});

package/get-package-json.js ADDED Viewed

@@ -0,0 +1,25 @@
+const path = require("path");
+const fs = require("fs");
+/**
+ * Resolves the directory of the package.json for a given dependency.
+ * @param {string} name - the package name
+ * @returns
+ *
+ * @description
+ * NodeJS exports fields prevent arbitrarily resolving files in a package
+ * that are not explicitly enumerated in the exports field of the package.
+ * This function provides a mechanism to resolve the package 'root' by package name,
+ * allowing file-system retrieval by relative path for arbitrary files outside of
+ * Node's module system.
+ */
+exports.getPackageJsonDir = (name, options) => {
+    const entry = require.resolve(name, options).toString();
+    let dir = path.parse(entry).dir;
+    while (!fs.existsSync(path.resolve(dir, "package.json"))) {
+        dir = path.parse(dir).dir;
+    }
+    return dir;
+};

package/package.json ADDED Viewed

@@ -0,0 +1,36 @@
+{
+  "name": "@microsoft/fast-build",
+  "version": "0.1.1",
+  "description": "CLI and Node.js API for server-side rendering of FAST declarative HTML templates.",
+  "author": {
+    "name": "Microsoft",
+    "url": "https://discord.gg/FcSNfg4"
+  },
+  "homepage": "https://www.fast.design/",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Microsoft/fast.git",
+    "directory": "packages/fast-build"
+  },
+  "bugs": {
+    "url": "https://github.com/microsoft/fast/issues/new/choose"
+  },
+  "bin": {
+    "fast": "./bin/fast.js"
+  },
+  "files": [
+    "bin",
+    "get-package-json.js",
+    "wasm/microsoft_fast_build.js",
+    "wasm/microsoft_fast_build_bg.wasm",
+    "wasm/microsoft_fast_build.d.ts",
+    "wasm/microsoft_fast_build_bg.wasm.d.ts"
+  ],
+  "scripts": {
+    "build:wasm": "wasm-pack build --target nodejs ../../crates/microsoft-fast-build --out-dir ../../packages/fast-build/wasm"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  }
+}

package/wasm/microsoft_fast_build.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Parse all `<f-template>` elements from an HTML string.
+ * Returns a JSON array of `{"name": string | null, "content": string}` objects,
+ * one per `<f-template>` element found. `name` is `null` when the element has
+ * no `name` attribute.
+ */
+export function parse_f_templates(html: string): string;
+/**
+ * Render a FAST HTML template with a JSON state string.
+ * Returns the rendered HTML or throws a JavaScript error.
+ */
+export function render(entry: string, state: string): string;
+/**
+ * Render a FAST HTML template with custom element templates and a JSON state string.
+ * `templates_json` is a JSON object mapping element names to their HTML template strings,
+ * e.g. `{"my-button": "<template>...</template>"}`.
+ * Returns the rendered HTML or throws a JavaScript error.
+ */
+export function render_with_templates(entry: string, templates_json: string, state: string): string;

package/wasm/microsoft_fast_build.js ADDED Viewed

@@ -0,0 +1,199 @@
+/* @ts-self-types="./microsoft_fast_build.d.ts" */
+/**
+ * Parse all `<f-template>` elements from an HTML string.
+ * Returns a JSON array of `{"name": string | null, "content": string}` objects,
+ * one per `<f-template>` element found. `name` is `null` when the element has
+ * no `name` attribute.
+ * @param {string} html
+ * @returns {string}
+ */
+function parse_f_templates(html) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.parse_f_templates(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+exports.parse_f_templates = parse_f_templates;
+/**
+ * Render a FAST HTML template with a JSON state string.
+ * Returns the rendered HTML or throws a JavaScript error.
+ * @param {string} entry
+ * @param {string} state
+ * @returns {string}
+ */
+function render(entry, state) {
+    let deferred4_0;
+    let deferred4_1;
+    try {
+        const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.render(ptr0, len0, ptr1, len1);
+        var ptr3 = ret[0];
+        var len3 = ret[1];
+        if (ret[3]) {
+            ptr3 = 0; len3 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred4_0 = ptr3;
+        deferred4_1 = len3;
+        return getStringFromWasm0(ptr3, len3);
+    } finally {
+        wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
+    }
+}
+exports.render = render;
+/**
+ * Render a FAST HTML template with custom element templates and a JSON state string.
+ * `templates_json` is a JSON object mapping element names to their HTML template strings,
+ * e.g. `{"my-button": "<template>...</template>"}`.
+ * Returns the rendered HTML or throws a JavaScript error.
+ * @param {string} entry
+ * @param {string} templates_json
+ * @param {string} state
+ * @returns {string}
+ */
+function render_with_templates(entry, templates_json, state) {
+    let deferred5_0;
+    let deferred5_1;
+    try {
+        const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(templates_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ret = wasm.render_with_templates(ptr0, len0, ptr1, len1, ptr2, len2);
+        var ptr4 = ret[0];
+        var len4 = ret[1];
+        if (ret[3]) {
+            ptr4 = 0; len4 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred5_0 = ptr4;
+        deferred5_1 = len4;
+        return getStringFromWasm0(ptr4, len4);
+    } finally {
+        wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
+    }
+}
+exports.render_with_templates = render_with_templates;
+function __wbg_get_imports() {
+    const import0 = {
+        __proto__: null,
+        __wbindgen_cast_0000000000000001: function(arg0, arg1) {
+            // Cast intrinsic for `Ref(String) -> Externref`.
+            const ret = getStringFromWasm0(arg0, arg1);
+            return ret;
+        },
+        __wbindgen_init_externref_table: function() {
+            const table = wasm.__wbindgen_externrefs;
+            const offset = table.grow(4);
+            table.set(0, undefined);
+            table.set(offset + 0, undefined);
+            table.set(offset + 1, null);
+            table.set(offset + 2, true);
+            table.set(offset + 3, false);
+        },
+    };
+    return {
+        __proto__: null,
+        "./microsoft_fast_build_bg.js": import0,
+    };
+}
+function getStringFromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return decodeText(ptr, len);
+}
+let cachedUint8ArrayMemory0 = null;
+function getUint8ArrayMemory0() {
+    if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+        cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+    }
+    return cachedUint8ArrayMemory0;
+}
+function passStringToWasm0(arg, malloc, realloc) {
+    if (realloc === undefined) {
+        const buf = cachedTextEncoder.encode(arg);
+        const ptr = malloc(buf.length, 1) >>> 0;
+        getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf);
+        WASM_VECTOR_LEN = buf.length;
+        return ptr;
+    }
+    let len = arg.length;
+    let ptr = malloc(len, 1) >>> 0;
+    const mem = getUint8ArrayMemory0();
+    let offset = 0;
+    for (; offset < len; offset++) {
+        const code = arg.charCodeAt(offset);
+        if (code > 0x7F) break;
+        mem[ptr + offset] = code;
+    }
+    if (offset !== len) {
+        if (offset !== 0) {
+            arg = arg.slice(offset);
+        }
+        ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+        const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+        const ret = cachedTextEncoder.encodeInto(arg, view);
+        offset += ret.written;
+        ptr = realloc(ptr, len, offset, 1) >>> 0;
+    }
+    WASM_VECTOR_LEN = offset;
+    return ptr;
+}
+function takeFromExternrefTable0(idx) {
+    const value = wasm.__wbindgen_externrefs.get(idx);
+    wasm.__externref_table_dealloc(idx);
+    return value;
+}
+let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true });
+cachedTextDecoder.decode();
+function decodeText(ptr, len) {
+    return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+const cachedTextEncoder = new TextEncoder();
+if (!('encodeInto' in cachedTextEncoder)) {
+    cachedTextEncoder.encodeInto = function (arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+            read: arg.length,
+            written: buf.length
+        };
+    };
+}
+let WASM_VECTOR_LEN = 0;
+const wasmPath = `${__dirname}/microsoft_fast_build_bg.wasm`;
+const wasmBytes = require('fs').readFileSync(wasmPath);
+const wasmModule = new WebAssembly.Module(wasmBytes);
+let wasm = new WebAssembly.Instance(wasmModule, __wbg_get_imports()).exports;
+wasm.__wbindgen_start();

package/wasm/microsoft_fast_build_bg.wasm ADDED Viewed

Binary file

package/wasm/microsoft_fast_build_bg.wasm.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const parse_f_templates: (a: number, b: number) => [number, number];
+export const render: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+export const render_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_start: () => void;