@monosmith/plugin-sdk 0.0.0-stage → 0.2.0

package/templating/render-template.algorithm.js

@@ -0,0 +1,87 @@
+import { parseTemplate } from './parse-template.algorithm.js';
+import { TEMPLATE_FUNCTIONS, byKey, format, isObject, isTruthy } from './template-functions.algorithm.js';
+import { TemplateError } from './template.error.js';
+/**
+ * Renders a `[[ ]]` template with the data, the way the Go SDK's `templating`
+ * does with `text/template` and `missingkey=error`: a field the data does not
+ * have is an error, not an empty string. See {@link parseTemplate} for the
+ * language. `name` is only used in error messages.
+ */
+export function renderTemplate(text, data, name = 'template') {
+    const fail = (message) => {
+        throw new TemplateError(name, message);
+    };
+    return render(parseTemplate(text, name), { dot: data, root: data }, fail);
+}
+function render(nodes, scope, fail) {
+    return nodes.map(node => renderNode(node, scope, fail)).join('');
+}
+function renderNode(node, scope, fail) {
+    if (node.type === 'text')
+        return node.text;
+    const value = evaluatePipeline(node.pipeline, scope, fail);
+    if (node.type === 'action')
+        return format(value);
+    if (node.type === 'if')
+        return render(isTruthy(value) ? node.body : node.otherwise, scope, fail);
+    if (node.type === 'with')
+        return isTruthy(value) ? render(node.body, { dot: value, root: scope.root }, fail) : render(node.otherwise, scope, fail);
+    const items = rangeItems(value, fail);
+    return items.length === 0 ? render(node.otherwise, scope, fail) : items.map(item => render(node.body, { dot: item, root: scope.root }, fail)).join('');
+}
+/** What `range` loops over: the elements of an array, or the values of a map in key order. */
+function rangeItems(value, fail) {
+    if (Array.isArray(value))
+        return value;
+    if (value === null || value === undefined)
+        return [];
+    return isObject(value) ? Object.keys(value).sort(byKey).map(key => value[key]) : fail(`range can't iterate over ${format(value)}`);
+}
+const NONE = Symbol('nothing piped');
+function evaluatePipeline(pipeline, scope, fail) {
+    let piped = NONE;
+    for (const command of pipeline)
+        piped = evaluateCommand(command, scope, piped, fail);
+    return piped;
+}
+function evaluateCommand(command, scope, piped, fail) {
+    const [head, ...rest] = command;
+    if (head.kind === 'name')
+        return callFunction(head.name, rest, scope, piped, fail);
+    if (rest.length > 0)
+        return fail('can\'t give an argument to a value that is not a function');
+    return piped === NONE ? evaluateOperand(head, scope, fail) : fail('can\'t pipe into a value that is not a function');
+}
+function callFunction(name, operands, scope, piped, fail) {
+    const fn = Object.hasOwn(TEMPLATE_FUNCTIONS, name) ? TEMPLATE_FUNCTIONS[name] : undefined;
+    if (fn === undefined)
+        return fail(`function "${name}" not defined`);
+    const args = operands.map(operand => evaluateOperand(operand, scope, fail));
+    if (piped !== NONE)
+        args.push(piped);
+    try {
+        return fn(args);
+    }
+    catch (error) {
+        return fail(`error calling ${name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function evaluateOperand(operand, scope, fail) {
+    if (operand.kind === 'nil')
+        return null;
+    if ('value' in operand)
+        return operand.value;
+    if (operand.kind === 'pipeline')
+        return evaluatePipeline(operand.pipeline, scope, fail);
+    if (operand.kind === 'name')
+        return evaluateCommand([operand], scope, NONE, fail);
+    let value = operand.root ? scope.root : scope.dot;
+    for (const key of operand.path) {
+        if (!isObject(value))
+            return fail(`can't evaluate field ${key} in ${value === null || value === undefined ? 'nil' : typeof value}`);
+        if (!Object.hasOwn(value, key))
+            return fail(`map has no entry for key "${key}"`);
+        value = value[key];
+    }
+    return value;
+}

package/templating/template-functions.algorithm.d.ts

@@ -0,0 +1,10 @@
+export type TemplateFunction = (args: unknown[]) => unknown;
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/** Keys in the order Go sorts the keys of a map in. */
+export declare function byKey(a: string, b: string): number;
+/** Go's truth: false, 0, nil, and an empty string, array or map are false; everything else is true. */
+export declare function isTruthy(value: unknown): boolean;
+/** A value as `text/template` prints it. */
+export declare function format(value: unknown): string;
+/** The functions of `text/template` the subset has. */
+export declare const TEMPLATE_FUNCTIONS: Readonly<Record<string, TemplateFunction>>;

package/templating/template-functions.algorithm.js

@@ -0,0 +1,104 @@
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Keys in the order Go sorts the keys of a map in. */
+export function byKey(a, b) {
+    return Number(a > b) - Number(a < b);
+}
+/** Go's truth: false, 0, nil, and an empty string, array or map are false; everything else is true. */
+export function isTruthy(value) {
+    if ([undefined, null, false, 0, ''].includes(value))
+        return false;
+    return Array.isArray(value) ? value.length > 0 : !isObject(value) || Object.keys(value).length > 0;
+}
+/** A value as `text/template` prints it. */
+export function format(value) {
+    if (value === undefined || value === null)
+        return '<no value>';
+    if (Array.isArray(value))
+        return `[${value.map(item => format(item)).join(' ')}]`;
+    if (!isObject(value))
+        return String(value);
+    const entries = Object.keys(value).sort(byKey).map(key => `${key}:${format(value[key])}`);
+    return `map[${entries.join(' ')}]`;
+}
+function comparable(a, b) {
+    const kind = typeof a;
+    if (typeof b !== kind || !['string', 'number', 'boolean'].includes(kind))
+        throw new TypeError('incompatible types for comparison');
+    return kind;
+}
+function ordered(test) {
+    return ([a, b]) => {
+        if (comparable(a, b) === 'boolean')
+            throw new TypeError('invalid type for comparison');
+        return test(a === b ? 0 : (Number(a > b) || -1));
+    };
+}
+function indexInto(current, key) {
+    if (Array.isArray(current)) {
+        if (typeof key !== 'number' || key < 0 || key >= current.length)
+            throw new RangeError(`index out of range: ${format(key)}`);
+        return current[key];
+    }
+    if (isObject(current))
+        return Object.hasOwn(current, String(key)) ? current[String(key)] : undefined;
+    throw new TypeError(`can't index ${format(current)}`);
+}
+/** What Sprint puts between operands: a space when neither side is a string. */
+function sprint(args) {
+    return args.reduce((out, arg, i) => {
+        const space = i > 0 && typeof arg !== 'string' && typeof args[i - 1] !== 'string';
+        return `${out}${space ? ' ' : ''}${format(arg)}`;
+    }, '');
+}
+/** The functions of `text/template` the subset has. */
+export const TEMPLATE_FUNCTIONS = {
+    eq: ([first, ...others]) => {
+        if (others.length === 0)
+            throw new TypeError('missing argument for comparison');
+        return others.some((other) => {
+            if (first === null || other === null)
+                return first === other;
+            comparable(first, other);
+            return first === other;
+        });
+    },
+    ne: ([a, b]) => {
+        if (a === null || b === null)
+            return a !== b;
+        comparable(a, b);
+        return a !== b;
+    },
+    lt: ordered(difference => difference < 0),
+    le: ordered(difference => difference <= 0),
+    gt: ordered(difference => difference > 0),
+    ge: ordered(difference => difference >= 0),
+    not: ([value]) => !isTruthy(value),
+    and: args => args.find(arg => !isTruthy(arg)) ?? args.at(-1),
+    or: args => args.find(arg => isTruthy(arg)) ?? args.at(-1),
+    len: ([value]) => {
+        if (typeof value === 'string')
+            return Buffer.byteLength(value);
+        if (Array.isArray(value))
+            return value.length;
+        if (isObject(value))
+            return Object.keys(value).length;
+        throw new TypeError(`len of ${format(value)}`);
+    },
+    index: ([value, ...keys]) => keys.reduce((current, key) => indexInto(current, key), value),
+    print: args => sprint(args),
+    printf: ([pattern, ...args]) => {
+        if (typeof pattern !== 'string')
+            throw new TypeError('printf needs a format string');
+        let next = 0;
+        return pattern.replaceAll(/%([%sdvqt])/g, (_match, verb) => {
+            if (verb === '%')
+                return '%';
+            if (next >= args.length)
+                throw new RangeError(`missing argument for %${verb}`);
+            const arg = args[next++];
+            return verb === 'q' ? JSON.stringify(String(arg)) : format(arg);
+        });
+    },
+};

package/templating/template-syntax.contract.d.ts

@@ -0,0 +1,33 @@
+/** One operand of a command: a field of the data, a literal, a parenthesised pipeline or a function name. */
+export type Operand = {
+    kind: 'field';
+    root: boolean;
+    path: string[];
+} | {
+    kind: 'string' | 'number' | 'bool';
+    value: string | number | boolean;
+} | {
+    kind: 'nil';
+} | {
+    kind: 'pipeline';
+    pipeline: Pipeline;
+} | {
+    kind: 'name';
+    name: string;
+};
+/** Operands in a row: a function call (`eq .Kind "app"`) or a single value. */
+export type Command = Operand[];
+/** Commands joined by `|`, each receiving the previous one's value as its last argument. */
+export type Pipeline = Command[];
+export type TemplateNode = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'action';
+    pipeline: Pipeline;
+} | {
+    type: 'if' | 'with' | 'range';
+    pipeline: Pipeline;
+    body: TemplateNode[];
+    otherwise: TemplateNode[];
+};

package/templating/template-syntax.contract.js

@@ -0,0 +1 @@
+export {};

package/templating/template.error.d.ts

@@ -0,0 +1,4 @@
+/** A template that cannot be parsed or rendered: bad syntax, a field the data does not have, a construct outside the supported subset. */
+export declare class TemplateError extends Error {
+    constructor(name: string, message: string);
+}

package/templating/template.error.js

@@ -0,0 +1,7 @@
+/** A template that cannot be parsed or rendered: bad syntax, a field the data does not have, a construct outside the supported subset. */
+export class TemplateError extends Error {
+    constructor(name, message) {
+        super(`template ${name}: ${message}`);
+        this.name = 'TemplateError';
+    }
+}

package/templating/tokenize-action.algorithm.d.ts

@@ -0,0 +1,20 @@
+export type Token = {
+    t: 'open' | 'close' | 'pipe';
+} | {
+    t: 'field';
+    root: boolean;
+    path: string[];
+} | {
+    t: 'string';
+    value: string;
+} | {
+    t: 'number';
+    value: number;
+} | {
+    t: 'word';
+    value: string;
+};
+/**
+ * Splits the text of an action into tokens. `fail` reports what cannot be a token.
+ */
+export declare function tokenizeAction(body: string, fail: (message: string) => never): Token[];

package/templating/tokenize-action.algorithm.js

@@ -0,0 +1,57 @@
+/**
+ * The elements of an action, in the order the alternatives are tried: space,
+ * brackets and pipe, a quoted or raw string, a number, a field (`.A.B`, `$`,
+ * `$.A`, or a lone `.`), a word, and `:=`/`=`, which are variables. Anything else
+ * is the last alternative, so every character belongs to some match.
+ */
+const ELEMENT = new RegExp([
+    String.raw `\s+`,
+    String.raw `(?<open>\()`,
+    String.raw `(?<close>\))`,
+    String.raw `(?<pipe>\|)`,
+    String.raw `(?<string>"(?:[^"\\]|\\.)*")`,
+    '(?<raw>`[^`]*`)',
+    String.raw `(?<number>-?\d+(?:\.\d+)?(?![\w.]))`,
+    String.raw `(?<field>\$(?:\.[A-Z_]\w*)*|(?:\.[A-Z_]\w*)+|\.)`,
+    String.raw `(?<word>[A-Z_]\w*)`,
+    '(?<variable>:?=)',
+    '(?<other>.)',
+].join('|'), 'gis');
+/**
+ * Splits the text of an action into tokens. `fail` reports what cannot be a token.
+ */
+export function tokenizeAction(body, fail) {
+    const tokens = [];
+    for (const match of body.matchAll(ELEMENT)) {
+        const found = match.groups ?? {};
+        if (found.open !== undefined)
+            tokens.push({ t: 'open' });
+        else if (found.close !== undefined)
+            tokens.push({ t: 'close' });
+        else if (found.pipe !== undefined)
+            tokens.push({ t: 'pipe' });
+        else if (found.string !== undefined)
+            tokens.push({ t: 'string', value: unquote(found.string, fail) });
+        else if (found.raw !== undefined)
+            tokens.push({ t: 'string', value: found.raw.slice(1, -1) });
+        else if (found.number !== undefined)
+            tokens.push({ t: 'number', value: Number(found.number) });
+        else if (found.field !== undefined)
+            tokens.push({ t: 'field', root: found.field.startsWith('$'), path: found.field.split('.').filter(part => part !== '' && part !== '$') });
+        else if (found.word !== undefined)
+            tokens.push({ t: 'word', value: found.word });
+        else if (found.variable !== undefined)
+            fail('variables are not supported by the SDK\'s templates');
+        else if (found.other !== undefined)
+            fail(`unexpected character "${found.other}" in action`);
+    }
+    return tokens;
+}
+function unquote(literal, fail) {
+    try {
+        return JSON.parse(literal);
+    }
+    catch {
+        return fail(`invalid string ${literal}`);
+    }
+}

package/templating/write-templates.use-case.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Renders every template in `files` (target path to template text) under
+ * `root` with `data`, creating directories as needed. A target path may itself
+ * contain template actions (`[[.Dir]]/main.ts`). Returns the written paths,
+ * forward-slashed and relative to `root`, in the order of the sorted templates.
+ *
+ * Nothing is written if any template fails to render or any target exists
+ * ({@link FileExistsError}): it never overwrites a file. A target that would
+ * land outside `root` is refused.
+ */
+export declare function writeTemplates(root: string, files: Record<string, string>, data?: unknown): Promise<string[]>;

package/templating/write-templates.use-case.js

@@ -0,0 +1,44 @@
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, posix, resolve, sep } from 'node:path';
+import { FileExistsError } from './file-exists.error.js';
+import { renderTemplate } from './render-template.algorithm.js';
+import { byKey } from './template-functions.algorithm.js';
+import { TemplateError } from './template.error.js';
+/**
+ * Renders every template in `files` (target path to template text) under
+ * `root` with `data`, creating directories as needed. A target path may itself
+ * contain template actions (`[[.Dir]]/main.ts`). Returns the written paths,
+ * forward-slashed and relative to `root`, in the order of the sorted templates.
+ *
+ * Nothing is written if any template fails to render or any target exists
+ * ({@link FileExistsError}): it never overwrites a file. A target that would
+ * land outside `root` is refused.
+ */
+export async function writeTemplates(root, files, data) {
+    const rendered = [];
+    for (const target of Object.keys(files).sort(byKey)) {
+        const path = posix.normalize(renderTemplate(target, data, 'path'));
+        const full = resolve(root, ...path.split('/'));
+        if (path === '..' || path.startsWith('../') || isAbsolute(path) || !full.startsWith(resolve(root) + sep)) {
+            throw new TemplateError(path, 'the target is outside the project root');
+        }
+        if (await exists(full))
+            throw new FileExistsError(path);
+        rendered.push({ path, content: renderTemplate(files[target], data, path) });
+    }
+    for (const file of rendered) {
+        const full = join(root, ...file.path.split('/'));
+        await mkdir(dirname(full), { recursive: true, mode: 0o755 });
+        await writeFile(full, file.content, { mode: 0o644 });
+    }
+    return rendered.map(file => file.path);
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}