@formfeed/engine 0.1.0

package/types/lib/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared contracts of `@formfeed/engine` (spec 05). Used by the Angular editor (browser) and the
+ * Fly.io render-worker (Node); nothing here may touch Node-only APIs.
+ */
+export type EngineId = 'jinja2' | 'liquid' | 'handlebars';
+/** 1-based line and column, end exclusive. */
+export interface Position {
+    line: number;
+    column: number;
+}
+export interface Range {
+    start: Position;
+    end: Position;
+}
+export type DiagnosticSeverity = 'error' | 'warning' | 'info';
+export interface Diagnostic {
+    severity: DiagnosticSeverity;
+    message: string;
+    range: Range;
+    /** Stable code the editor keys quick-fixes and docs on, e.g. `unknown-filter`. */
+    code: string;
+    /** Optional quick-fix: replace the range with `replacement`. */
+    fix?: {
+        title: string;
+        replacement: string;
+    };
+}
+export interface VariableRef {
+    path: string[];
+    range: Range;
+    kind: 'read' | 'loop-var' | 'assigned';
+}
+export interface FilterRef {
+    name: string;
+    range: Range;
+    known: boolean;
+}
+export interface IncludeRef {
+    name: string;
+    range: Range;
+}
+export interface BlockRef {
+    type: 'for' | 'if' | 'block' | 'raw' | 'macro' | 'other';
+    open: Range;
+    close?: Range;
+}
+export interface Analysis {
+    variables: VariableRef[];
+    filters: FilterRef[];
+    includes: IncludeRef[];
+    blocks: BlockRef[];
+    diagnostics: Diagnostic[];
+}
+export interface AnalyzeOptions {
+    /** Sample data; when given, variable paths missing from it produce warnings. */
+    sampleData?: unknown;
+    /** Helper registry that decides which filter names are known. Defaults to the built-in set. */
+    helpers?: HelperRegistry;
+}
+/** Resolves a workspace partial by name to its source; `undefined` when it does not exist. */
+export type PartialResolver = (name: string) => string | undefined;
+export interface RenderLimits {
+    /** Wall-clock budget of one render in milliseconds. */
+    ms: number;
+    /** Maximum size of the rendered HTML in bytes. */
+    outputBytes: number;
+    /** Maximum nesting of includes and extends. */
+    includeDepth: number;
+}
+export interface RenderContext {
+    locale: string;
+    timezone: string;
+    currency: string;
+    partials: PartialResolver;
+    helpers: HelperRegistry;
+    limits: RenderLimits;
+    /** Template-level dictionaries for `t()`: locale → key → text (USP-8). */
+    i18n?: Record<string, Record<string, string>>;
+    /** Base URL for `asset()` (workspace asset root on the CDN). */
+    assetBaseUrl?: string;
+}
+export interface CompileOptions {
+    /** Name used in error messages and as the root include name. */
+    name?: string;
+}
+export interface CompiledTemplate {
+    engine: EngineId;
+    name: string;
+    source: string;
+    render(data: unknown, ctx: RenderContext): Promise<string>;
+}
+export interface Engine {
+    id: EngineId;
+    /** Parses and compiles; throws `EngineSyntaxError` with line and column. */
+    compile(source: string, opts?: CompileOptions): CompiledTemplate;
+    analyze(source: string, opts?: AnalyzeOptions): Analysis;
+    render(tpl: CompiledTemplate, data: unknown, ctx: RenderContext): Promise<string>;
+}
+export type HelperCategory = 'format' | 'text' | 'collection' | 'logic' | 'code' | 'document' | 'debug';
+export interface HelperDoc {
+    signature: string;
+    description: string;
+    example: string;
+    category: HelperCategory;
+}
+export interface HelperDefinition {
+    name: string;
+    /** Other names the helper answers to (apitemplate.io compatibility aliases). */
+    aliases?: string[];
+    /** Result is HTML that must not be escaped by the engine. */
+    html?: boolean;
+    /** Emits a warning diagnostic pointing to the preferred name (deprecated aliases). */
+    deprecatedAlias?: Record<string, string>;
+    doc: HelperDoc;
+    /** Receives the render context first, then the template arguments. */
+    fn: (ctx: HelperContext, ...args: unknown[]) => unknown;
+}
+/** What helpers know about the current render without receiving the whole context. */
+export interface HelperContext {
+    locale: string;
+    timezone: string;
+    currency: string;
+    i18n?: Record<string, Record<string, string>>;
+    assetBaseUrl?: string;
+}
+export interface HelperRegistry {
+    /** Registered helpers keyed by canonical name. */
+    readonly definitions: ReadonlyMap<string, HelperDefinition>;
+    /** Resolves a name or alias. */
+    get(name: string): HelperDefinition | undefined;
+    has(name: string): boolean;
+    /** Every name the engines know, aliases included. */
+    names(): string[];
+    /** Concrete functions bound to a render context, keyed by every name and alias. */
+    bind(ctx: HelperContext): Map<string, {
+        fn: (...args: unknown[]) => unknown;
+        html: boolean;
+    }>;
+    register(definition: HelperDefinition): void;
+}

package/types/types/modules.d.cts

@@ -0,0 +1,85 @@
+/* Ambient typings for deep imports the engine relies on (browser-safe builds). */
+
+declare module 'nunjucks/browser/nunjucks.js' {
+  import type * as N from 'nunjucks';
+
+  /** Nunjucks AST node; every node carries a 0-based `lineno`/`colno` and lists its child fields. */
+  export interface NunjucksNode {
+    typename: string;
+    lineno: number;
+    colno: number;
+    fields: string[];
+    children?: NunjucksNode[];
+    value?: unknown;
+    [field: string]: unknown;
+  }
+
+  export interface NunjucksCompiler {
+    _emit(code: string): void;
+    compile(node: unknown, frame: unknown): void;
+  }
+
+  export interface NunjucksModule {
+    Environment: typeof N.Environment;
+    Template: typeof N.Template;
+    Loader: typeof N.Loader;
+    runtime: typeof N.runtime & {
+      memberLookup: (obj: unknown, val: unknown, ...rest: unknown[]) => unknown;
+    };
+    /** The code generator; patched for `not` precedence (engines/jinja2.ts). */
+    compiler: {
+      Compiler: {
+        prototype: {
+          compileNot(this: NunjucksCompiler, node: { target: unknown }, frame: unknown): void;
+        };
+      };
+    };
+    lib: {
+      TemplateError: new (
+        message: string,
+        lineno?: number,
+        colno?: number,
+      ) => Error;
+    };
+    installJinjaCompat: () => void;
+    parser: {
+      parse(
+        src: string,
+        extensions?: unknown[],
+        opts?: Record<string, unknown>,
+      ): NunjucksNode;
+    };
+    nodes: Record<string, unknown>;
+  }
+
+  const nunjucks: NunjucksModule;
+  export default nunjucks;
+}
+
+declare module 'qrcode/lib/renderer/svg-tag.js' {
+  import type { QRCode } from 'qrcode';
+  export function render(
+    qrData: QRCode,
+    options?: {
+      width?: number;
+      margin?: number;
+      scale?: number;
+      color?: { dark?: string; light?: string };
+    },
+  ): string;
+}
+
+declare module 'bwip-js' {
+  /** Symbology rendering options; `bcid` and `text` are required. */
+  export interface RenderOptions {
+    bcid: string;
+    text: string;
+    scale?: number;
+    height?: number;
+    width?: number;
+    includetext?: boolean;
+    textxalign?: string;
+    [option: string]: unknown;
+  }
+  export function toSVG(options: RenderOptions): string;
+}

package/types/types/modules.d.ts

@@ -0,0 +1,85 @@
+/* Ambient typings for deep imports the engine relies on (browser-safe builds). */
+
+declare module 'nunjucks/browser/nunjucks.js' {
+  import type * as N from 'nunjucks';
+
+  /** Nunjucks AST node; every node carries a 0-based `lineno`/`colno` and lists its child fields. */
+  export interface NunjucksNode {
+    typename: string;
+    lineno: number;
+    colno: number;
+    fields: string[];
+    children?: NunjucksNode[];
+    value?: unknown;
+    [field: string]: unknown;
+  }
+
+  export interface NunjucksCompiler {
+    _emit(code: string): void;
+    compile(node: unknown, frame: unknown): void;
+  }
+
+  export interface NunjucksModule {
+    Environment: typeof N.Environment;
+    Template: typeof N.Template;
+    Loader: typeof N.Loader;
+    runtime: typeof N.runtime & {
+      memberLookup: (obj: unknown, val: unknown, ...rest: unknown[]) => unknown;
+    };
+    /** The code generator; patched for `not` precedence (engines/jinja2.ts). */
+    compiler: {
+      Compiler: {
+        prototype: {
+          compileNot(this: NunjucksCompiler, node: { target: unknown }, frame: unknown): void;
+        };
+      };
+    };
+    lib: {
+      TemplateError: new (
+        message: string,
+        lineno?: number,
+        colno?: number,
+      ) => Error;
+    };
+    installJinjaCompat: () => void;
+    parser: {
+      parse(
+        src: string,
+        extensions?: unknown[],
+        opts?: Record<string, unknown>,
+      ): NunjucksNode;
+    };
+    nodes: Record<string, unknown>;
+  }
+
+  const nunjucks: NunjucksModule;
+  export default nunjucks;
+}
+
+declare module 'qrcode/lib/renderer/svg-tag.js' {
+  import type { QRCode } from 'qrcode';
+  export function render(
+    qrData: QRCode,
+    options?: {
+      width?: number;
+      margin?: number;
+      scale?: number;
+      color?: { dark?: string; light?: string };
+    },
+  ): string;
+}
+
+declare module 'bwip-js' {
+  /** Symbology rendering options; `bcid` and `text` are required. */
+  export interface RenderOptions {
+    bcid: string;
+    text: string;
+    scale?: number;
+    height?: number;
+    width?: number;
+    includetext?: boolean;
+    textxalign?: string;
+    [option: string]: unknown;
+  }
+  export function toSVG(options: RenderOptions): string;
+}