@formfeed/engine 0.3.5 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/engine",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "The Formfeed template engine (Jinja2, Liquid, Handlebars) for the browser and Node.",
   "license": "MIT",
   "type": "module",

package/types/index.d.cts

@@ -1,7 +1,8 @@
 export * from './lib/types.cjs';
 export { EngineSyntaxError, RenderError, RenderLimitError } from './lib/errors.cjs';
 export { defaultLimits, depthGuard, enforceLimits } from './lib/limits.cjs';
-export { DefaultHelperRegistry, builtinHelpers, chartMarkup, chartPayload, createHelperRegistry, defaultHelpers, epcPayload, escapeHtml, helperDocs, imageMarkup, qrSvg, toDate, toNumber, } from './lib/helpers/index.cjs';
+export { DefaultHelperRegistry, EPC_MAX_BYTES, builtinHelpers, chartMarkup, chartPayload, createHelperRegistry, defaultHelpers, epcPayload, escapeHtml, helperDocs, ibanChecksum, imageMarkup, normaliseIban, qrSvg, svgDataUri, toDate, toNumber, validateEpc, } from './lib/helpers/index.cjs';
+export type { EpcInput, EpcPayment, EpcProblem, QrOptions } from './lib/helpers/index.cjs';
 export { analyzeHandlebars, analyzeJinja2, analyzeLiquid, engineIds, engines, getEngine, handlebarsEngine, jinja2Engine, liquidEngine, liquidBuiltinFilters, nunjucksBuiltinFilters, } from './lib/engines/index.cjs';
 export { diffSchemas, inferSchema, inferSchemaFromDataSets, schemaPaths } from './lib/schema.cjs';
 export { defaultOutput, imageOutput, isOfficeKind, isOutputFormat, officeKinds, outputFormats, outputsForKind, type OfficeKind, type OutputFormat, } from './lib/output.cjs';

package/types/index.d.ts

@@ -1,7 +1,8 @@
 export * from './lib/types.js';
 export { EngineSyntaxError, RenderError, RenderLimitError } from './lib/errors.js';
 export { defaultLimits, depthGuard, enforceLimits } from './lib/limits.js';
-export { DefaultHelperRegistry, builtinHelpers, chartMarkup, chartPayload, createHelperRegistry, defaultHelpers, epcPayload, escapeHtml, helperDocs, imageMarkup, qrSvg, toDate, toNumber, } from './lib/helpers/index.js';
+export { DefaultHelperRegistry, EPC_MAX_BYTES, builtinHelpers, chartMarkup, chartPayload, createHelperRegistry, defaultHelpers, epcPayload, escapeHtml, helperDocs, ibanChecksum, imageMarkup, normaliseIban, qrSvg, svgDataUri, toDate, toNumber, validateEpc, } from './lib/helpers/index.js';
+export type { EpcInput, EpcPayment, EpcProblem, QrOptions } from './lib/helpers/index.js';
 export { analyzeHandlebars, analyzeJinja2, analyzeLiquid, engineIds, engines, getEngine, handlebarsEngine, jinja2Engine, liquidEngine, liquidBuiltinFilters, nunjucksBuiltinFilters, } from './lib/engines/index.js';
 export { diffSchemas, inferSchema, inferSchemaFromDataSets, schemaPaths } from './lib/schema.js';
 export { defaultOutput, imageOutput, isOfficeKind, isOutputFormat, officeKinds, outputFormats, outputsForKind, type OfficeKind, type OutputFormat, } from './lib/output.js';

package/types/lib/codes/epc.d.cts

@@ -0,0 +1,56 @@
+/**
+ * The SEPA credit transfer QR code, EPC069-12 version 002 — the GiroCode a German invoice carries
+ * so a banking app fills the transfer in by scanning it (spec 05 §2, `epcQr`).
+ *
+ * The payload is built here and validated here, apart from the helper registration, so the browser
+ * can have both without the rest of the engine: `helpers/codes.ts` also brings bwip-js in for
+ * barcodes, which is far larger than everything on this page put together.
+ */
+/**
+ * A complete payment. A caller that has one should say so with this type; the two functions below
+ * take `EpcInput` instead, because a template hands over whatever the data happened to hold and
+ * telling someone what is missing is the whole job of `validateEpc`.
+ */
+export interface EpcPayment {
+    /** The beneficiary, at most 70 characters. Required. */
+    name: string;
+    /** The beneficiary's IBAN. Required. */
+    iban: string;
+    /** Optional with version 002 inside SEPA; 8 or 11 characters. */
+    bic?: string;
+    /** Euro; the code carries no other currency. */
+    amount?: number | string;
+    /** Structured remittance information, at most 35 characters. Excludes `text`. */
+    reference?: string;
+    /** Unstructured remittance information, at most 140 characters. Excludes `reference`. */
+    text?: string;
+    /** Purpose code (AT-44), at most 4 characters. */
+    purpose?: string;
+}
+/** What a caller actually hands over: the same fields, none of them guaranteed to be there. */
+export type EpcInput = Partial<EpcPayment>;
+/** EPC QR (GiroCode) payload, version 002, UTF-8, SCT. */
+export declare function epcPayload(input: EpcInput): string;
+/**
+ * What is wrong with a payment, as a code rather than a sentence: the engine has no locale, and the
+ * one caller that shows these to a person says them in two languages.
+ */
+export interface EpcProblem {
+    field: keyof EpcPayment | 'payload';
+    code: 'required' | 'too_long' | 'iban_characters' | 'iban_country_length' | 'iban_checksum' | 'bic_format' | 'not_a_number' | 'out_of_range' | 'reference_or_text';
+    /** The limit that was passed, where there is one. */
+    max?: number;
+    /** What the value actually is, where a number says more than the code alone. */
+    actual?: number;
+}
+/** The whole payload must fit 331 bytes, and a German umlaut is two of them. */
+export declare const EPC_MAX_BYTES = 331;
+/** Spaces and case are the writer's business, not the code's. */
+export declare const normaliseIban: (iban: string) => string;
+/**
+ * Whether an IBAN's check digits match its body (ISO 7064 mod 97-10). The remainder is taken digit
+ * by digit because the rearranged number runs to 30-odd digits, well past a safe integer.
+ */
+export declare function ibanChecksum(iban: string): boolean;
+/** Everything wrong with a payment, in the order a form shows its fields; empty when it is valid. */
+export declare function validateEpc(input: EpcInput): EpcProblem[];

package/types/lib/codes/epc.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The SEPA credit transfer QR code, EPC069-12 version 002 — the GiroCode a German invoice carries
+ * so a banking app fills the transfer in by scanning it (spec 05 §2, `epcQr`).
+ *
+ * The payload is built here and validated here, apart from the helper registration, so the browser
+ * can have both without the rest of the engine: `helpers/codes.ts` also brings bwip-js in for
+ * barcodes, which is far larger than everything on this page put together.
+ */
+/**
+ * A complete payment. A caller that has one should say so with this type; the two functions below
+ * take `EpcInput` instead, because a template hands over whatever the data happened to hold and
+ * telling someone what is missing is the whole job of `validateEpc`.
+ */
+export interface EpcPayment {
+    /** The beneficiary, at most 70 characters. Required. */
+    name: string;
+    /** The beneficiary's IBAN. Required. */
+    iban: string;
+    /** Optional with version 002 inside SEPA; 8 or 11 characters. */
+    bic?: string;
+    /** Euro; the code carries no other currency. */
+    amount?: number | string;
+    /** Structured remittance information, at most 35 characters. Excludes `text`. */
+    reference?: string;
+    /** Unstructured remittance information, at most 140 characters. Excludes `reference`. */
+    text?: string;
+    /** Purpose code (AT-44), at most 4 characters. */
+    purpose?: string;
+}
+/** What a caller actually hands over: the same fields, none of them guaranteed to be there. */
+export type EpcInput = Partial<EpcPayment>;
+/** EPC QR (GiroCode) payload, version 002, UTF-8, SCT. */
+export declare function epcPayload(input: EpcInput): string;
+/**
+ * What is wrong with a payment, as a code rather than a sentence: the engine has no locale, and the
+ * one caller that shows these to a person says them in two languages.
+ */
+export interface EpcProblem {
+    field: keyof EpcPayment | 'payload';
+    code: 'required' | 'too_long' | 'iban_characters' | 'iban_country_length' | 'iban_checksum' | 'bic_format' | 'not_a_number' | 'out_of_range' | 'reference_or_text';
+    /** The limit that was passed, where there is one. */
+    max?: number;
+    /** What the value actually is, where a number says more than the code alone. */
+    actual?: number;
+}
+/** The whole payload must fit 331 bytes, and a German umlaut is two of them. */
+export declare const EPC_MAX_BYTES = 331;
+/** Spaces and case are the writer's business, not the code's. */
+export declare const normaliseIban: (iban: string) => string;
+/**
+ * Whether an IBAN's check digits match its body (ISO 7064 mod 97-10). The remainder is taken digit
+ * by digit because the rearranged number runs to 30-odd digits, well past a safe integer.
+ */
+export declare function ibanChecksum(iban: string): boolean;
+/** Everything wrong with a payment, in the order a form shows its fields; empty when it is valid. */
+export declare function validateEpc(input: EpcInput): EpcProblem[];

package/types/lib/codes/index.d.cts

@@ -0,0 +1,7 @@
+/**
+ * Codes without the engine: QR rendering and the EPC (GiroCode) payload with its validation, for a
+ * caller that wants them in a browser and nothing else. `@formfeed/engine/codes` in this workspace;
+ * the published package exposes the same functions from its single entry.
+ */
+export { EPC_MAX_BYTES, epcPayload, ibanChecksum, normaliseIban, validateEpc, type EpcInput, type EpcPayment, type EpcProblem, } from './epc.cjs';
+export { qrSvg, svgDataUri, type QrOptions } from './qr.cjs';

package/types/lib/codes/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Codes without the engine: QR rendering and the EPC (GiroCode) payload with its validation, for a
+ * caller that wants them in a browser and nothing else. `@formfeed/engine/codes` in this workspace;
+ * the published package exposes the same functions from its single entry.
+ */
+export { EPC_MAX_BYTES, epcPayload, ibanChecksum, normaliseIban, validateEpc, type EpcInput, type EpcPayment, type EpcProblem, } from './epc.js';
+export { qrSvg, svgDataUri, type QrOptions } from './qr.js';

package/types/lib/codes/qr.d.cts

@@ -0,0 +1,11 @@
+/** QR rendering, without the barcode symbologies `helpers/codes.ts` also registers. */
+export interface QrOptions {
+    size?: number;
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    margin?: number;
+    color?: string;
+    background?: string;
+}
+export declare function qrSvg(value: string, options?: QrOptions): string;
+/** An SVG as the `src` of an `<img>`, which is how the helpers put a code into a document. */
+export declare const svgDataUri: (svg: string) => string;

package/types/lib/codes/qr.d.ts

@@ -0,0 +1,11 @@
+/** QR rendering, without the barcode symbologies `helpers/codes.ts` also registers. */
+export interface QrOptions {
+    size?: number;
+    ecc?: 'L' | 'M' | 'Q' | 'H';
+    margin?: number;
+    color?: string;
+    background?: string;
+}
+export declare function qrSvg(value: string, options?: QrOptions): string;
+/** An SVG as the `src` of an `<img>`, which is how the helpers put a code into a document. */
+export declare const svgDataUri: (svg: string) => string;

package/types/lib/helpers/codes.d.cts

@@ -1,21 +1,2 @@
 import type { HelperDefinition } from '../types.cjs';
-type QrOptions = {
-    size?: number;
-    ecc?: 'L' | 'M' | 'Q' | 'H';
-    margin?: number;
-    color?: string;
-    background?: string;
-};
-export declare function qrSvg(value: string, options?: QrOptions): string;
-/** EPC QR (GiroCode) payload, version 002, UTF-8, SCT. */
-export declare function epcPayload(input: {
-    name: string;
-    iban: string;
-    bic?: string;
-    amount?: number | string;
-    reference?: string;
-    text?: string;
-    purpose?: string;
-}): string;
 export declare const codeHelpers: HelperDefinition[];
-export {};

package/types/lib/helpers/codes.d.ts

@@ -1,21 +1,2 @@
 import type { HelperDefinition } from '../types.js';
-type QrOptions = {
-    size?: number;
-    ecc?: 'L' | 'M' | 'Q' | 'H';
-    margin?: number;
-    color?: string;
-    background?: string;
-};
-export declare function qrSvg(value: string, options?: QrOptions): string;
-/** EPC QR (GiroCode) payload, version 002, UTF-8, SCT. */
-export declare function epcPayload(input: {
-    name: string;
-    iban: string;
-    bic?: string;
-    amount?: number | string;
-    reference?: string;
-    text?: string;
-    purpose?: string;
-}): string;
 export declare const codeHelpers: HelperDefinition[];
-export {};

package/types/lib/helpers/format.d.cts

@@ -1,5 +1,6 @@
 import type { HelperDefinition } from '../types.cjs';
-export declare function toNumber(value: unknown): number;
+import { toNumber } from '../values.cjs';
+export { toNumber };
 export declare function toDate(value: unknown, tz: string): Date | null;
 export declare function escapeHtml(value: string): string;
 export declare const formatHelpers: HelperDefinition[];

package/types/lib/helpers/format.d.ts

@@ -1,5 +1,6 @@
 import type { HelperDefinition } from '../types.js';
-export declare function toNumber(value: unknown): number;
+import { toNumber } from '../values.js';
+export { toNumber };
 export declare function toDate(value: unknown, tz: string): Date | null;
 export declare function escapeHtml(value: string): string;
 export declare const formatHelpers: HelperDefinition[];

package/types/lib/helpers/index.d.cts

@@ -1,8 +1,9 @@
-import type { HelperDefinition, HelperDoc } from '../types.cjs';
+import type { HelperDefinition, HelperDocEntry } from '../types.cjs';
 import { DefaultHelperRegistry } from './registry.cjs';
 export { DefaultHelperRegistry } from './registry.cjs';
 export { escapeHtml, toDate, toNumber } from './format.cjs';
-export { epcPayload, qrSvg } from './codes.cjs';
+export { EPC_MAX_BYTES, epcPayload, ibanChecksum, normaliseIban, qrSvg, svgDataUri, validateEpc } from '../codes/index.cjs';
+export type { EpcInput, EpcPayment, EpcProblem, QrOptions } from '../codes/index.cjs';
 export { chartMarkup, chartPayload, imageMarkup } from './document.cjs';
 export { officeUnsupported, officeUnsupportedHelpers } from './office.cjs';
 export type { ChartSpec, ImageOptions } from './document.cjs';
@@ -12,7 +13,4 @@ export declare function createHelperRegistry(extra?: HelperDefinition[]): Defaul
 /** Lazily built default registry, shared by analyze() and the engines when none is supplied. */
 export declare function defaultHelpers(): DefaultHelperRegistry;
 /** Documentation entries that feed editor hover and completion (spec 05 §2). */
-export declare function helperDocs(registry?: DefaultHelperRegistry): Array<HelperDoc & {
-    name: string;
-    aliases: string[];
-}>;
+export declare function helperDocs(registry?: DefaultHelperRegistry): HelperDocEntry[];

package/types/lib/helpers/index.d.ts

@@ -1,8 +1,9 @@
-import type { HelperDefinition, HelperDoc } from '../types.js';
+import type { HelperDefinition, HelperDocEntry } from '../types.js';
 import { DefaultHelperRegistry } from './registry.js';
 export { DefaultHelperRegistry } from './registry.js';
 export { escapeHtml, toDate, toNumber } from './format.js';
-export { epcPayload, qrSvg } from './codes.js';
+export { EPC_MAX_BYTES, epcPayload, ibanChecksum, normaliseIban, qrSvg, svgDataUri, validateEpc } from '../codes/index.js';
+export type { EpcInput, EpcPayment, EpcProblem, QrOptions } from '../codes/index.js';
 export { chartMarkup, chartPayload, imageMarkup } from './document.js';
 export { officeUnsupported, officeUnsupportedHelpers } from './office.js';
 export type { ChartSpec, ImageOptions } from './document.js';
@@ -12,7 +13,4 @@ export declare function createHelperRegistry(extra?: HelperDefinition[]): Defaul
 /** Lazily built default registry, shared by analyze() and the engines when none is supplied. */
 export declare function defaultHelpers(): DefaultHelperRegistry;
 /** Documentation entries that feed editor hover and completion (spec 05 §2). */
-export declare function helperDocs(registry?: DefaultHelperRegistry): Array<HelperDoc & {
-    name: string;
-    aliases: string[];
-}>;
+export declare function helperDocs(registry?: DefaultHelperRegistry): HelperDocEntry[];

package/types/lib/types.d.cts

@@ -119,9 +119,22 @@ export type HelperCategory = 'format' | 'text' | 'collection' | 'logic' | 'code'
 export interface HelperDoc {
     signature: string;
     description: string;
-    example: string;
+    /**
+     * The same call written for each engine, so the reference and the editor can show the reader the
+     * one they can paste. They differ in more than punctuation — Jinja2 passes filter arguments in
+     * parentheses, Liquid after a colon, Handlebars positionally — and `helper-examples.spec.ts`
+     * renders every one of them, so none of the three can be wrong.
+     */
+    examples: Record<EngineId, string>;
     category: HelperCategory;
 }
+/** A helper's documentation with the name it is registered under. What `helperDocs()` returns. */
+export interface HelperDocEntry extends HelperDoc {
+    name: string;
+    aliases: string[];
+    /** The Jinja2 example, for readers written before `examples`. */
+    example: string;
+}
 export interface HelperDefinition {
     name: string;
     /** Other names the helper answers to (apitemplate.io compatibility aliases). */

package/types/lib/types.d.ts

@@ -119,9 +119,22 @@ export type HelperCategory = 'format' | 'text' | 'collection' | 'logic' | 'code'
 export interface HelperDoc {
     signature: string;
     description: string;
-    example: string;
+    /**
+     * The same call written for each engine, so the reference and the editor can show the reader the
+     * one they can paste. They differ in more than punctuation — Jinja2 passes filter arguments in
+     * parentheses, Liquid after a colon, Handlebars positionally — and `helper-examples.spec.ts`
+     * renders every one of them, so none of the three can be wrong.
+     */
+    examples: Record<EngineId, string>;
     category: HelperCategory;
 }
+/** A helper's documentation with the name it is registered under. What `helperDocs()` returns. */
+export interface HelperDocEntry extends HelperDoc {
+    name: string;
+    aliases: string[];
+    /** The Jinja2 example, for readers written before `examples`. */
+    example: string;
+}
 export interface HelperDefinition {
     name: string;
     /** Other names the helper answers to (apitemplate.io compatibility aliases). */

package/types/lib/values.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Value coercions small enough that a module may want them without the rest of the engine. They
+ * live here rather than in `helpers/format.ts`, which pulls in date-fns, marked and n2words: the
+ * landing site's GiroCode tool imports `lib/codes` in the browser and would otherwise carry all
+ * three for the sake of one eight-line function.
+ */
+/** A number from whatever the data holds; `NaN` when it is not a number at all. */
+export declare function toNumber(value: unknown): number;

package/types/lib/values.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Value coercions small enough that a module may want them without the rest of the engine. They
+ * live here rather than in `helpers/format.ts`, which pulls in date-fns, marked and n2words: the
+ * landing site's GiroCode tool imports `lib/codes` in the browser and would otherwise carry all
+ * three for the sake of one eight-line function.
+ */
+/** A number from whatever the data holds; `NaN` when it is not a number at all. */
+export declare function toNumber(value: unknown): number;