Files
hypit/packages/text/src/program.ts
kashorin 4d1ac02104 refactor: close remaining 0.4 execution boundaries
Extract renderer-neutral local HTML execution, keep Chromium and Electron backends independent, bound Producer inline values, and harden public diagnostics and text handling.
2026-10-31 02:28:46 +08:00

559 lines
20 KiB
TypeScript

import { canonicalize } from "@hypit/protocol";
import type {
Text,
TextBinding,
TextBindings,
TextBindingValue,
TextCondition,
TextExpression,
TextScalar,
TextTemplate,
TextTransform,
} from "./types.js";
const NAME = /^[a-z][a-z0-9-]{0,95}$/u;
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
}
function object(value: unknown, subject: string): Record<string, unknown> {
assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
return value as Record<string, unknown>;
}
function name(value: unknown, subject: string): asserts value is string {
assert(typeof value === "string" && NAME.test(value), `${subject} must be a lower-kebab name`);
}
function scalar(value: unknown, subject: string): asserts value is TextScalar {
assert(
typeof value === "string"
|| typeof value === "boolean"
|| (typeof value === "number" && Number.isFinite(value)),
`${subject} must be text, boolean or a finite number`,
);
}
function bindingValue(value: unknown, subject: string): asserts value is TextBindingValue {
if (!Array.isArray(value)) {
scalar(value, subject);
return;
}
value.forEach((item, index) => scalar(item, `${subject}[${index}]`));
}
function condition(value: unknown, subject: string): asserts value is TextCondition {
const item = object(value, subject);
if (item.kind === "present") {
name(item.binding, `${subject}.binding`);
return;
}
if (item.kind === "equals") {
name(item.binding, `${subject}.binding`);
scalar(item.value, `${subject}.value`);
return;
}
if (item.kind === "all" || item.kind === "any") {
assert(Array.isArray(item.conditions) && item.conditions.length > 0, `${subject}.conditions must be non-empty`);
item.conditions.forEach((entry, index) => condition(entry, `${subject}.conditions[${index}]`));
return;
}
if (item.kind === "not") {
condition(item.condition, `${subject}.condition`);
return;
}
throw new Error(`${subject}.kind is invalid`);
}
function transform(value: unknown, subject: string): asserts value is TextTransform {
const item = object(value, subject);
assert(
item.kind === "trim"
|| item.kind === "trim-start"
|| item.kind === "trim-end"
|| item.kind === "uppercase"
|| item.kind === "lowercase"
|| item.kind === "collapse-whitespace"
|| item.kind === "normalize-newlines"
|| item.kind === "json-string",
`${subject}.kind is invalid`,
);
}
function expression(
value: unknown,
subject: string,
calls: Set<string>,
): asserts value is TextExpression {
const item = object(value, subject);
if (item.kind === "literal") {
assert(typeof item.value === "string", `${subject}.value must be text`);
return;
}
if (item.kind === "slot") {
name(item.binding, `${subject}.binding`);
return;
}
if (item.kind === "sequence" || item.kind === "join") {
assert(Array.isArray(item.items), `${subject}.items must be an array`);
if (item.kind === "join") {
assert(typeof item.separator === "string", `${subject}.separator must be text`);
assert(item.omitEmpty === undefined || typeof item.omitEmpty === "boolean", `${subject}.omitEmpty must be boolean`);
}
item.items.forEach((entry, index) => expression(entry, `${subject}.items[${index}]`, calls));
return;
}
if (item.kind === "choice") {
assert(Array.isArray(item.cases) && item.cases.length > 0, `${subject}.cases must be non-empty`);
item.cases.forEach((entry, index) => {
const candidate = object(entry, `${subject}.cases[${index}]`);
condition(candidate.when, `${subject}.cases[${index}].when`);
expression(candidate.value, `${subject}.cases[${index}].value`, calls);
});
if (item.otherwise !== undefined) expression(item.otherwise, `${subject}.otherwise`, calls);
return;
}
if (item.kind === "optional") {
condition(item.when, `${subject}.when`);
expression(item.value, `${subject}.value`, calls);
return;
}
if (item.kind === "each") {
name(item.binding, `${subject}.binding`);
name(item.as, `${subject}.as`);
assert(typeof item.separator === "string", `${subject}.separator must be text`);
expression(item.value, `${subject}.value`, calls);
return;
}
if (item.kind === "replace") {
expression(item.input, `${subject}.input`, calls);
assert(Array.isArray(item.replacements), `${subject}.replacements must be an array`);
item.replacements.forEach((entry, index) => {
const replacement = object(entry, `${subject}.replacements[${index}]`);
assert(typeof replacement.from === "string" && replacement.from.length > 0,
`${subject}.replacements[${index}].from must be non-empty text`);
assert(typeof replacement.to === "string", `${subject}.replacements[${index}].to must be text`);
assert(replacement.mode === "first" || replacement.mode === "all",
`${subject}.replacements[${index}].mode is invalid`);
});
return;
}
if (item.kind === "transform") {
expression(item.input, `${subject}.input`, calls);
assert(Array.isArray(item.transforms) && item.transforms.length > 0, `${subject}.transforms must be non-empty`);
item.transforms.forEach((entry, index) => transform(entry, `${subject}.transforms[${index}]`));
return;
}
if (item.kind === "call") {
name(item.template, `${subject}.template`);
calls.add(item.template);
return;
}
throw new Error(`${subject}.kind is invalid`);
}
function callGraph(template: TextTemplate): Map<string, Set<string>> {
const graph = new Map<string, Set<string>>();
const rootCalls = new Set<string>();
expression(template.root, "TextTemplate.root", rootCalls);
graph.set("$root", rootCalls);
for (const [id, value] of Object.entries(template.definitions ?? {})) {
name(id, `TextTemplate.definitions key ${id}`);
const calls = new Set<string>();
expression(value, `TextTemplate.definitions.${id}`, calls);
graph.set(id, calls);
}
return graph;
}
function verifyFiniteCalls(template: TextTemplate): void {
const graph = callGraph(template);
for (const [from, calls] of graph) {
for (const target of calls) {
assert(graph.has(target), `TextTemplate ${from} calls unknown definition ${target}`);
}
}
const visiting = new Set<string>();
const visited = new Set<string>();
const visit = (id: string) => {
if (visited.has(id)) return;
assert(!visiting.has(id), `TextTemplate call cycle reaches ${id}`);
visiting.add(id);
for (const target of graph.get(id) ?? []) visit(target);
visiting.delete(id);
visited.add(id);
};
visit("$root");
for (const id of graph.keys()) visit(id);
}
export function verifyText(value: unknown): asserts value is Text {
const item = object(value, "Text");
assert(typeof item.value === "string", "Text is invalid");
}
export function sealText(value: string): Text {
const result = canonicalize({ value }) as unknown as Text;
verifyText(result);
return result;
}
export function verifyTextBindings(value: unknown): asserts value is TextBindings {
const item = object(value, "TextBindings");
const values = object(item.values, "TextBindings.values");
for (const [id, entry] of Object.entries(values)) {
name(id, `TextBindings.values key ${id}`);
bindingValue(entry, `TextBindings.values.${id}`);
}
}
export function sealTextBindings(values: Readonly<Record<string, TextBindingValue>> = {}): TextBindings {
const result = canonicalize({ values }) as unknown as TextBindings;
verifyTextBindings(result);
return result;
}
export function verifyTextBinding(value: unknown): asserts value is TextBinding {
const item = object(value, "TextBinding");
name(item.name, "TextBinding.name");
assert(item.mode === "set" || item.mode === "append", "TextBinding.mode is invalid");
}
export function sealTextBinding(value: TextBinding): TextBinding {
const result = canonicalize({ ...value }) as unknown as TextBinding;
verifyTextBinding(result);
return result;
}
export function bindText(
bindings: TextBindings,
binding: TextBinding,
text: Text,
): TextBindings {
verifyTextBindings(bindings);
verifyTextBinding(binding);
verifyText(text);
const existing = bindings.values[binding.name];
if (binding.mode === "set") {
assert(existing === undefined, `Text binding ${binding.name} is already set`);
return sealTextBindings({ ...bindings.values, [binding.name]: text.value });
}
if (existing === undefined) return sealTextBindings({ ...bindings.values, [binding.name]: [text.value] });
const values = Array.isArray(existing) ? [...existing] : [existing];
return sealTextBindings({ ...bindings.values, [binding.name]: [...values, text.value] });
}
export function verifyTextTemplate(value: unknown): asserts value is TextTemplate {
const template = object(value, "TextTemplate") as unknown as TextTemplate;
if (template.defaults !== undefined) {
const defaults = object(template.defaults, "TextTemplate.defaults");
for (const [id, entry] of Object.entries(defaults)) {
name(id, `TextTemplate.defaults key ${id}`);
bindingValue(entry, `TextTemplate.defaults.${id}`);
}
}
if (template.definitions !== undefined) object(template.definitions, "TextTemplate.definitions");
verifyFiniteCalls(template);
}
export function sealTextTemplate(value: TextTemplate): TextTemplate {
const result = canonicalize(value) as unknown as TextTemplate;
verifyTextTemplate(result);
return result;
}
function collectBindings(
value: TextExpression,
template: TextTemplate,
result: Set<string>,
locals: ReadonlySet<string>,
definitions: Map<TextExpression, Map<string, readonly string[]>>,
): void {
const add = (id: string) => { if (!locals.has(id)) result.add(id); };
const collectCondition = (item: TextCondition): void => {
if (item.kind === "present" || item.kind === "equals") {
add(item.binding);
return;
}
if (item.kind === "all" || item.kind === "any") {
item.conditions.forEach(collectCondition);
return;
}
collectCondition(item.condition);
};
if (value.kind === "literal") return;
if (value.kind === "slot") {
add(value.binding);
return;
}
if (value.kind === "sequence" || value.kind === "join") {
value.items.forEach((item) => collectBindings(item, template, result, locals, definitions));
return;
}
if (value.kind === "choice") {
value.cases.forEach((item) => {
collectCondition(item.when);
collectBindings(item.value, template, result, locals, definitions);
});
if (value.otherwise !== undefined) collectBindings(value.otherwise, template, result, locals, definitions);
return;
}
if (value.kind === "optional") {
collectCondition(value.when);
collectBindings(value.value, template, result, locals, definitions);
return;
}
if (value.kind === "each") {
add(value.binding);
collectBindings(value.value, template, result, new Set([...locals, value.as]), definitions);
return;
}
if (value.kind === "replace" || value.kind === "transform") {
collectBindings(value.input, template, result, locals, definitions);
return;
}
const definition = template.definitions?.[value.template];
if (definition === undefined) return;
const scope = JSON.stringify([...locals].sort());
const cached = definitions.get(definition)?.get(scope);
if (cached !== undefined) {
cached.forEach((id) => result.add(id));
return;
}
const contributed = new Set<string>();
collectBindings(definition, template, contributed, locals, definitions);
let scopes = definitions.get(definition);
if (scopes === undefined) {
scopes = new Map();
definitions.set(definition, scopes);
}
scopes.set(scope, [...contributed]);
contributed.forEach((id) => result.add(id));
}
export function textTemplateBindingNames(template: TextTemplate): ReadonlySet<string> {
verifyTextTemplate(template);
const result = new Set<string>();
collectBindings(template.root, template, result, new Set(), new Map());
return result;
}
function hasBinding(bindings: Readonly<Record<string, TextBindingValue>>, id: string): boolean {
const value = bindings[id];
return value !== undefined && (!Array.isArray(value) || value.length > 0);
}
function matches(value: TextCondition, bindings: Readonly<Record<string, TextBindingValue>>): boolean {
if (value.kind === "present") return hasBinding(bindings, value.binding);
if (value.kind === "equals") {
const actual = bindings[value.binding];
return !Array.isArray(actual) && actual === value.value;
}
if (value.kind === "all") return value.conditions.every((item) => matches(item, bindings));
if (value.kind === "any") return value.conditions.some((item) => matches(item, bindings));
return !matches(value.condition, bindings);
}
function scalarText(value: TextBindingValue | undefined, subject: string): string {
assert(value !== undefined, `${subject} is missing`);
assert(!Array.isArray(value), `${subject} is a list and must be consumed by each`);
return String(value);
}
function applyTransform(value: string, operation: TextTransform): string {
if (operation.kind === "trim") return value.trim();
if (operation.kind === "trim-start") return value.trimStart();
if (operation.kind === "trim-end") return value.trimEnd();
if (operation.kind === "uppercase") return value.toUpperCase();
if (operation.kind === "lowercase") return value.toLowerCase();
if (operation.kind === "collapse-whitespace") return value.replace(/\s+/gu, " ").trim();
if (operation.kind === "normalize-newlines") return value.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
return JSON.stringify(value);
}
export type TextRenderOptions = {
/** Limit for the canonical `{ value: string }` returned by this render. */
readonly maxInlineValueBytes?: number;
};
type TextRenderBuffer = {
readonly chunks: string[];
readonly maxInlineValueBytes: number | undefined;
escapedBytes: number;
pendingHighSurrogate: boolean;
};
const textValueJsonOverhead = Buffer.byteLength('{"value":""}', "utf8");
function createTextRenderBuffer(maxInlineValueBytes: number | undefined): TextRenderBuffer {
if (maxInlineValueBytes !== undefined) {
assert(Number.isSafeInteger(maxInlineValueBytes) && maxInlineValueBytes > 0,
"Text render maxInlineValueBytes must be a positive safe integer");
assert(maxInlineValueBytes >= textValueJsonOverhead,
`Text render inline Value limit ${maxInlineValueBytes} bytes cannot contain an empty Text value`);
}
return { chunks: [], maxInlineValueBytes, escapedBytes: 0, pendingHighSurrogate: false };
}
function escapedCodeUnitBytes(value: number): number {
if (value === 0x22 || value === 0x5c || value === 0x08 || value === 0x09
|| value === 0x0a || value === 0x0c || value === 0x0d) return 2;
if (value < 0x20 || (value >= 0xdc00 && value <= 0xdfff)) return 6;
if (value <= 0x7f) return 1;
if (value <= 0x7ff) return 2;
return 3;
}
function assertTextRenderBudget(output: TextRenderBuffer, final: boolean): void {
const bytes = textValueJsonOverhead + output.escapedBytes
+ (output.pendingHighSurrogate ? (final ? 6 : 4) : 0);
if (output.maxInlineValueBytes !== undefined) {
assert(bytes <= output.maxInlineValueBytes,
`Text render exceeds the ${output.maxInlineValueBytes}-byte inline Value limit`);
}
}
function countRendered(output: TextRenderBuffer, value: string): void {
for (let index = 0; index < value.length; index += 1) {
const unit = value.charCodeAt(index);
if (output.pendingHighSurrogate) {
if (unit >= 0xdc00 && unit <= 0xdfff) {
output.escapedBytes += 4;
output.pendingHighSurrogate = false;
continue;
}
output.escapedBytes += 6;
output.pendingHighSurrogate = false;
}
if (unit >= 0xd800 && unit <= 0xdbff) output.pendingHighSurrogate = true;
else output.escapedBytes += escapedCodeUnitBytes(unit);
}
assertTextRenderBudget(output, false);
}
function appendRendered(output: TextRenderBuffer, value: string): void {
if (value.length === 0) return;
countRendered(output, value);
output.chunks.push(value);
}
function renderExpressionValue(
value: TextExpression,
template: TextTemplate,
bindings: Readonly<Record<string, TextBindingValue>>,
maxInlineValueBytes?: number,
): string {
const output = createTextRenderBuffer(maxInlineValueBytes);
renderExpression(value, template, bindings, output);
assertTextRenderBudget(output, true);
return output.chunks.join("");
}
function replaceLiteral(value: string, from: string, to: string, all: boolean, maxInlineValueBytes?: number): string {
const output = createTextRenderBuffer(maxInlineValueBytes);
let cursor = 0;
while (cursor <= value.length) {
const found = value.indexOf(from, cursor);
if (found < 0) {
appendRendered(output, value.slice(cursor));
break;
}
appendRendered(output, value.slice(cursor, found));
appendRendered(output, to);
cursor = found + from.length;
if (!all) {
appendRendered(output, value.slice(cursor));
break;
}
}
assertTextRenderBudget(output, true);
return output.chunks.join("");
}
function renderExpression(
value: TextExpression,
template: TextTemplate,
bindings: Readonly<Record<string, TextBindingValue>>,
output: TextRenderBuffer,
): void {
if (value.kind === "literal") { appendRendered(output, value.value); return; }
if (value.kind === "slot") {
appendRendered(output, scalarText(bindings[value.binding], `Text binding ${value.binding}`));
return;
}
if (value.kind === "sequence") {
value.items.forEach((item) => renderExpression(item, template, bindings, output));
return;
}
if (value.kind === "join") {
let written = false;
for (const item of value.items) {
const rendered = renderExpressionValue(item, template, bindings, output.maxInlineValueBytes);
if (value.omitEmpty === true && rendered.length === 0) continue;
if (written) appendRendered(output, value.separator);
appendRendered(output, rendered);
written = true;
}
return;
}
if (value.kind === "choice") {
const selected = value.cases.filter((item) => matches(item.when, bindings));
assert(selected.length <= 1, `Text choice matched ${selected.length} cases`);
if (selected.length === 1) {
renderExpression(selected[0]!.value, template, bindings, output);
return;
}
assert(value.otherwise !== undefined, "Text choice matched no case and has no otherwise branch");
renderExpression(value.otherwise, template, bindings, output);
return;
}
if (value.kind === "optional") {
if (matches(value.when, bindings)) renderExpression(value.value, template, bindings, output);
return;
}
if (value.kind === "each") {
const source = bindings[value.binding];
assert(Array.isArray(source), `Text binding ${value.binding} must be a list`);
source.forEach((item, index) => {
if (index > 0) appendRendered(output, value.separator);
renderExpression(value.value, template, { ...bindings, [value.as]: item }, output);
});
return;
}
if (value.kind === "replace") {
let result = renderExpressionValue(value.input, template, bindings, output.maxInlineValueBytes);
for (const replacement of value.replacements) {
result = replaceLiteral(result, replacement.from, replacement.to, replacement.mode === "all", output.maxInlineValueBytes);
}
appendRendered(output, result);
return;
}
if (value.kind === "transform") {
const result = value.transforms.reduce(
(result, operation) => applyTransform(result, operation),
renderExpressionValue(value.input, template, bindings, output.maxInlineValueBytes),
);
appendRendered(output, result);
return;
}
const definition = template.definitions?.[value.template];
assert(definition !== undefined, `TextTemplate definition ${value.template} is missing`);
renderExpression(definition, template, bindings, output);
}
export function renderText(template: TextTemplate, bindings: TextBindings, options: TextRenderOptions = {}): Text {
verifyTextTemplate(template);
verifyTextBindings(bindings);
const known = textTemplateBindingNames(template);
for (const id of Object.keys(template.defaults ?? {})) {
assert(known.has(id), `TextTemplate default ${id} is not consumed`);
}
for (const id of Object.keys(bindings.values)) {
assert(known.has(id), `Text binding ${id} is not declared by the template`);
}
return sealText(renderExpressionValue(template.root, template, { ...template.defaults, ...bindings.values },
options.maxInlineValueBytes));
}