@ovineko/spa-guard-node 0.0.1-alpha-18

package/dist/index.js

@@ -0,0 +1,135 @@
+// src/node/index.ts
+import { matchLang, translations } from "@ovineko/spa-guard/i18n";
+import { negotiate } from "@fastify/accept-negotiator";
+import { extractVersionFromHtml } from "@ovineko/spa-guard/_internal";
+import { matchLang as matchLang2, translations as translations2 } from "@ovineko/spa-guard/i18n";
+import { createHash } from "crypto";
+import { promisify } from "util";
+import { brotliCompress, gzip, zstdCompress } from "zlib";
+import { parse, html as parse5Html, serialize } from "parse5";
+var gzipAsync = promisify(gzip);
+var brotliAsync = promisify(brotliCompress);
+var zstdAsync = promisify(zstdCompress);
+async function createHtmlCache(options) {
+  const { html, translations: customTranslations } = options;
+  const merged = mergeTranslations(customTranslations);
+  const mergedKeys = new Set(Object.keys(merged));
+  const languages = (options.languages ?? Object.keys(merged)).filter(
+    (lang) => mergedKeys.has(lang)
+  );
+  if (languages.length === 0) {
+    throw new Error("createHtmlCache requires at least one language");
+  }
+  const version = extractVersionFromHtml(html);
+  const sha256Prefix = version ? null : createHash("sha256").update(html).digest("hex").slice(0, 16);
+  const entries = /* @__PURE__ */ new Map();
+  await Promise.all(
+    languages.map(async (lang) => {
+      const patched = patchHtmlI18n({ html, lang, translations: customTranslations });
+      const buf = Buffer.from(patched, "utf8");
+      const etag = version ? `"${version}-${lang}"` : `"${sha256Prefix}-${lang}"`;
+      const [gzipped, brotli, zstdBuf] = await Promise.all([
+        gzipAsync(buf),
+        brotliAsync(buf),
+        zstdAsync(buf)
+      ]);
+      entries.set(lang, {
+        br: brotli,
+        etag,
+        gzip: gzipped,
+        identity: buf,
+        lang,
+        zstd: zstdBuf
+      });
+    })
+  );
+  const available = languages;
+  return {
+    get({ acceptEncoding, acceptLanguage, lang: langOverride }) {
+      const resolvedLang = matchLang2(langOverride ?? acceptLanguage, available);
+      const entry = entries.get(resolvedLang) ?? entries.get(available[0]);
+      const headers = {
+        "Content-Language": entry.lang,
+        "Content-Type": "text/html; charset=utf-8",
+        ETag: entry.etag,
+        Vary: "Accept-Language, Accept-Encoding"
+      };
+      if (!acceptEncoding) {
+        return { body: entry.identity, headers };
+      }
+      const encoding = negotiate(acceptEncoding, ["br", "zstd", "gzip"]);
+      if (!encoding) {
+        return { body: entry.identity, headers };
+      }
+      headers["Content-Encoding"] = encoding;
+      const bodyMap = {
+        br: entry.br,
+        gzip: entry.gzip,
+        zstd: entry.zstd
+      };
+      return { body: bodyMap[encoding], headers };
+    }
+  };
+}
+function patchHtmlI18n(options) {
+  const { acceptLanguage, html, lang: langOverride, translations: customTranslations } = options;
+  const merged = mergeTranslations(customTranslations);
+  const available = Object.keys(merged);
+  const input = langOverride ?? acceptLanguage;
+  const resolvedLang = matchLang2(input, available);
+  const t = merged[resolvedLang];
+  if (resolvedLang === "en" && !customTranslations?.en) {
+    return html;
+  }
+  if (!t) {
+    return html;
+  }
+  const doc = parse(html);
+  const htmlEl = doc.childNodes.find(
+    (n) => n.nodeName === "html"
+  );
+  if (!htmlEl) {
+    return html;
+  }
+  const langAttr = htmlEl.attrs.find((a) => a.name === "lang");
+  if (langAttr) {
+    langAttr.value = resolvedLang;
+  } else {
+    htmlEl.attrs.push({ name: "lang", value: resolvedLang });
+  }
+  const headEl = htmlEl.childNodes.find(
+    (n) => n.nodeName === "head"
+  );
+  if (!headEl) {
+    return html;
+  }
+  const meta = {
+    attrs: [
+      { name: "name", value: "spa-guard-i18n" },
+      { name: "content", value: JSON.stringify(t) }
+    ],
+    childNodes: [],
+    namespaceURI: parse5Html.NS.HTML,
+    nodeName: "meta",
+    parentNode: headEl,
+    tagName: "meta"
+  };
+  headEl.childNodes.unshift(meta);
+  return serialize(doc);
+}
+function mergeTranslations(customTranslations) {
+  const merged = { ...translations2 };
+  if (customTranslations) {
+    for (const [key, partial] of Object.entries(customTranslations)) {
+      const base = merged[key];
+      merged[key] = base ? { ...base, ...partial } : partial;
+    }
+  }
+  return merged;
+}
+export {
+  createHtmlCache,
+  matchLang,
+  patchHtmlI18n,
+  translations
+};

package/dist/node/index.d.ts

@@ -0,0 +1,54 @@
+export type { SpaGuardTranslations } from "@ovineko/spa-guard/i18n";
+export { matchLang, translations } from "@ovineko/spa-guard/i18n";
+import type { SpaGuardTranslations } from "@ovineko/spa-guard/i18n";
+export interface CreateHtmlCacheOptions {
+    /** The HTML string to cache */
+    html: string;
+    /** Languages to pre-generate (defaults to all keys from built-in + custom translations) */
+    languages?: string[];
+    /** Custom translations (deep-merged per-language with built-ins) */
+    translations?: Record<string, Partial<SpaGuardTranslations>>;
+}
+export interface HtmlCache {
+    get(options: {
+        acceptEncoding?: string;
+        acceptLanguage?: string;
+        lang?: string;
+    }): HtmlCacheResponse;
+}
+export interface HtmlCacheResponse {
+    body: Buffer | string;
+    headers: Record<string, string>;
+}
+export interface PatchHtmlI18nOptions {
+    /** Raw Accept-Language header value */
+    acceptLanguage?: string;
+    /** The HTML string to patch */
+    html: string;
+    /** Explicit language override (takes priority over acceptLanguage) */
+    lang?: string;
+    /** Custom translations (deep-merged per-language with built-ins) */
+    translations?: Record<string, Partial<SpaGuardTranslations>>;
+}
+/**
+ * Create a pre-computed HTML cache with compressed variants for all languages.
+ *
+ * At startup, generates all language variants via patchHtmlI18n and
+ * pre-compresses each with gzip, brotli, and zstd. ETag is derived from
+ * `__SPA_GUARD_VERSION__` in the HTML (falls back to sha256 prefix).
+ *
+ * The returned cache's `get()` method resolves language via `matchLang`
+ * and negotiates encoding via Accept-Encoding, returning a ready-to-use
+ * response with body and headers.
+ */
+export declare function createHtmlCache(options: CreateHtmlCacheOptions): Promise<HtmlCache>;
+/**
+ * Server-side HTML patching for i18n.
+ *
+ * Resolves language from `lang` (explicit) or `acceptLanguage` (header),
+ * merges translations, and injects a `<meta name="spa-guard-i18n">` tag
+ * into `<head>`. Also updates `<html lang="...">`.
+ *
+ * English without custom translations is a no-op (returns unchanged HTML).
+ */
+export declare function patchHtmlI18n(options: PatchHtmlI18nOptions): string;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ovineko/spa-guard-node",
+  "version": "0.0.1-alpha-18",
+  "description": "Server-side HTML patching and i18n for spa-guard",
+  "keywords": [
+    "spa",
+    "node",
+    "i18n",
+    "html",
+    "server-side"
+  ],
+  "homepage": "https://github.com/ovineko/ovineko/tree/main/spa-guard/node",
+  "bugs": {
+    "url": "https://github.com/ovineko/ovineko/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ovineko/ovineko.git",
+    "directory": "spa-guard/node"
+  },
+  "license": "MIT",
+  "author": "Alexander Svinarev <shibanet0@gmail.com> (shibanet0.com)",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "default": "./dist/node/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@fastify/accept-negotiator": "2.0.1",
+    "@ovineko/spa-guard": "0.0.1-alpha-18"
+  },
+  "peerDependencies": {
+    "parse5": "^8"
+  },
+  "engines": {
+    "node": ">=22.15.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}