JavaScript API

Custom pipes run synchronously in an ES2020 JavaScript runtime. Their TypeScript entry point is bundled before execution.

export function transform(this: tCtx, input: Buffer): string | Buffer | TransformResult
export function index(this: iCtx, input: Buffer): unknown

The generated declarations are in .falz/types/.

Transform context: tCtx

Fragment context: fCtx

Fragment transforms receive the following context:

A source-less fragment has no file and receives an empty input buffer. Content variables remain available as top-level properties for compatibility (for example, this.lang), but cannot overwrite context fields. All values, including colliding names, remain accessible through this.vars.

Fragments are rendered per layout context, not per page: they do not receive a current page or output URL. Fragment indexing and KV access are not supported.

export function transform(this: fCtx): string {
  switch (this.name) {
    case 'nav': return renderNav(this.vars.lang)
    case 'footer': return renderFooter(this.vars.lang)
    default: throw new Error(`Unknown fragment: ${this.name}`)
  }
}

Declare <Fragment name="nav" pipe="shell"/> without a dummy source file. See Layout reference.

FileInfo

For content/posts/hello.md:

TransformResult

interface TransformResult {
  content: string | Buffer
  alias?: string
  vars?: Record<string, string>
}

Fields:

• content — transformed output inserted into the matching content slot;
• alias — optional value for {ALIAS} in the output path;
• vars — optional string values added to the layout variables. Keys identify layout placeholders and variables in expressions.

Returning another JavaScript value converts it to a string, but relying on that is less clear. Returning null or undefined is an error. An object must contain a string or Buffer content field.

Index context: iCtx

iCtx has file, globals, vars, and entry, with the same meanings as above. It also has kv: IndexKV, the write-only collector used to publish cross-entry values during indexing.

The return value of index() must be JSON-serializable. Falz stores it as this entry's blob, making it available later through this.blob.get() in transform(). See Index phase.

Index data

IndexKV

• set(key: string, value: unknown): void — store a JSON-serializable value during index(). key must have the form namespace:key, and the namespace must be in contract.provides.

KV

• get(key: string): unknown — return a decoded value, or null when missing.
• keys(prefix: string): string[] — return matching full keys in sorted order.

Only namespaces declared in the pipe's contract.consumes are loaded for its transforms.

Blob

• get(): unknown — lazily decode this entry's own index() result, or return null if none exists.

Repeated calls in one transform return the same decoded value.

Built-in modules

Use ESM imports:

import { text, json } from "fs"
import { get } from "http"
import { toHtml } from "md"

Falz externalizes these names during bundling and provides them at runtime.

fs

The fs module is read-only and rooted at the project source tree. It cannot read the scheme tree, output tree, or arbitrary host paths.

FileEntry has name, /-prefixed slash-normalized path, size, modTime, isFile, isDirectory, and isSymlink. Directories report size 0.

Example:

import { json, walk } from "fs"

const settings = json("data/settings.json") ?? {}
const images = walk("images").filter(entry => entry.isFile)

Reads through fs are available to the pipe, but they are not automatically represented as individual layout dependencies. If output freshness depends on another file, arrange your workflow so a relevant entry changes or use an indexed namespace to fan out invalidation.

http

The HTTP API is synchronous. Configure an allowlist in the pipe's config.yaml; no hosts are allowed by default.

url may be a string or URL. Headers may be a Headers object, a string-valued object, or [name, value][].

Body encoding:

• string: text/plain;charset=UTF-8;
• Buffer, Uint8Array, or ArrayBuffer: application/octet-stream;
• object or array: JSON with application/json;charset=UTF-8.

Set Content-Type explicitly in headers to override inference.

All methods throw for non-2xx responses. The error has status and response properties:

import { get, type Response } from "http"

try {
  const value = get("https://api.example.com/item").json()
} catch (error) {
  const e = error as Error & { status: number, response: Response }
  console.error(e.status, e.response.text())
}

Response

Properties:

• status: number — status code;
• statusText: string — standard status text;
• ok: boolean — true for 2xx;
• redirected: boolean — whether the final URL differs;
• url: string — final URL;
• headers: Headers — response headers.

Methods:

• text(): string — decode body bytes as text;
• json(): any — parse JSON; throws for empty or malformed bodies;
• bytes(): Buffer — return a Buffer;
• arrayBuffer(): ArrayBuffer — return an ArrayBuffer.

The body is buffered, so these accessors may be called more than once.

Headers

Construct with new Headers(), another Headers, a plain object, or pairs.

• append(name, value) — add another value;
• delete(name) — remove all values for the name;
• get(name) — comma-join values, or return null;
• has(name) — test whether the name exists;
• set(name, value) — replace existing values;
• entries() — iterator of [name, value] pairs;
• keys() — iterator of names;
• values() — iterator of values;
• forEach(callback, thisArg?) — visit (value, name, headers);
• getSetCookie() — return separate Set-Cookie values.

md

toHtml(markdown, options?)

Converts a string or Buffer to an HTML string.

import { commonOptions, toHtml } from "md"
return toHtml(input, commonOptions)

With no options, no optional parser/renderer flags are enabled. commonOptions enables common parsing features and smart punctuation.

options.parser boolean flags:

options.renderer boolean flags:

Unknown option keys are ignored.

tpl

render(template, variables)

Renders a string or Buffer with Plush and returns a string:

import { render } from "tpl"
return render("Hello <%= name %>", { name: "Ada" })

<%= expression %> emits escaped output; <% statement %> executes control flow without output. Syntax and missing-variable errors throw.

fasttpl

compile(template, params, config?)

Replaces tagged placeholders and returns a string:

import { compile } from "fasttpl"
compile("Hello {{name}}", { name: "Ada" })

Values may be strings or zero-argument functions returning strings. Unknown tags remain unchanged. config.startTag and config.endTag change delimiters; defaults are {{ and }}.

yaml

• parse(src: string | Buffer): any — parse one YAML document; malformed YAML throws.
• stringify(value, options?): string — serialize a value and include a trailing newline. options.indent is a positive number and defaults to 2. Function-valued and symbol-keyed properties are omitted.

Globals

console

• console.log(...data) and console.info(...data) — info log;
• console.warn(...data) — warning;
• console.error(...data) — error;
• console.dump(...data) — pretty-print JSON-like values at info level.

Buffer

A Node-compatible Buffer subset is global. Common static methods are:

• Buffer.from(string | array | ArrayBuffer, encoding?);
• Buffer.alloc(size, fill?, encoding?);
• Buffer.concat(buffers, totalLength?);
• Buffer.isBuffer(value) and Buffer.isEncoding(name);
• Buffer.byteLength(value, encoding?) and Buffer.compare(a, b).

Instances provide write, toString, equals, numeric reads (readUInt*, readInt*, readBigInt*, readFloat*, readDouble*) and matching numeric writes. UInt/Uint aliases are available. Endian-specific methods use LE or BE.

Supported general encodings are utf8, utf-8, base64, base64url, and hex. Buffer.from() and buffer.toString() additionally accept latin1 and binary.

Base64

• atob(input): string — decode base64 to Latin-1 code points;
• btoa(input): string — encode Latin-1; throws for characters above 0xff.

URL

URL supports construction with an optional base; mutable hash, host, hostname, href, password, pathname, port, protocol, search, and username; read-only origin and searchParams; and toString()/toJSON().

URLSearchParams provides append, delete, entries, forEach, get, getAll, has, keys, set, sort, toString, values, size, and iteration.

Current declarations also mention domainToASCII and domainToUnicode, but the runtime only installs URL and URLSearchParams as globals. Do not depend on those domain helpers.

Not available

Do not assume a full browser or Node environment. In particular, use the Falz modules instead of global fetch, Node's writable fs, process, or worker APIs. An unknown runtime require() returns undefined and logs a warning; npm imports should have been bundled before runtime.