JS/TS API Docs

The JS/TS package is generated from the Rust renderer with wasm-pack. It is intended for websites and web apps that want to render Copperlace configuration in the browser.

Build

Install wasm-pack before building the JS/TS package.

Build the bundler package:

make js-package

Build a direct browser ES module package:

make js-web

Both commands write generated files to js/pkg/. The generated package is a build artifact and is not committed.

Bundler Usage

Use this shape with Vite, Webpack, SvelteKit, Next, or similar bundlers:

import {
  Copperlace,
  renderStringInferred,
  renderStringInferredWithContext,
  renderString,
  renderStringWithContext,
  renderStringWithProcessors,
} from "./pkg/copperlace";

const config = `
name = ["Mia", "Lina"]
origin {
  title = "Hello {name}"
  tags = ["structured", "{name | slug}"]
}
text = "Hello {name}"
`;

const copperlace = new Copperlace(config);
const first = copperlace.renderInferred("origin");
const second = copperlace.renderInferred("origin");
const seeded = copperlace.renderInferredWithContext("origin", { name: "Darcy" });
const custom = Copperlace.withProcessors(config, {
  shout: (value) => value.toUpperCase(),
}).render("text");

const oneShot = renderStringInferred(config, "origin");
const seededOneShot = renderStringInferredWithContext(config, "origin", { name: "Lina" });
const textOnly = renderString(config, "text");
const seededTextOnly = renderStringWithContext(config, "text", { name: "Lina" });
const customOneShot = renderStringWithProcessors(config, "text", {
  shout: (value) => value.toUpperCase(),
});

Inferred rendering returns text for text-valued rules and formatted JSON text for object-valued structured rules. Formatted structured JSON uses tabs by default.

Direct Browser Usage

Use make js-web for direct browser imports:

<script type="module">
  import init, { Copperlace } from "./pkg/copperlace.js";

  await init();

  const response = await fetch("./example.conf");
  const config = await response.text();
  const copperlace = new Copperlace(config);

  document.body.textContent = copperlace.renderInferred("origin");
</script>

API

new Copperlace(config: string): Compiles configuration once and returns a renderer for repeated renders.
Copperlace.withProcessors(config: string, processors: Record<string, (value: string) ⇒ string>): Compiles configuration once with custom processor functions. Custom processor names override builtin names.
Copperlace.render(rule: string): string: Renders a named text rule. Each call uses a fresh render context.
Copperlace.renderWithContext(rule: string, context: Record<string, string>): string: Renders a named text rule with initial context values for this render only.
Copperlace.renderInferred(rule: string): string: Renders a named rule, inferring the output mode. Text rules return text, and object-valued structured rules return formatted JSON text.
Copperlace.renderInferredWithContext(rule: string, context: Record<string, string>): string: Renders a named rule with initial context values, inferring text or formatted structured JSON output for this render only.
renderString(config: string, rule: string): string: Compiles config, renders one text rule, and releases the compiled ruleset.
renderStringWithContext(config: string, rule: string, context: Record<string, string>): string: Compiles config, renders one text rule with initial context values, and releases the compiled ruleset.
renderStringInferred(config: string, rule: string): string: Compiles config, renders one rule with inferred text or formatted structured JSON output, and releases the compiled ruleset.
renderStringInferredWithContext(config: string, rule: string, context: Record<string, string>): string: Compiles config, renders one rule with initial context values and inferred text or formatted structured JSON output, and releases the compiled ruleset.
renderStringWithProcessors(config: string, rule: string, processors: Record<string, (value: string) ⇒ string>): string: Compiles config with custom processor functions, renders one rule, and releases the compiled ruleset.
renderStringWithProcessorsAndContext(config: string, rule: string, processors: Record<string, (value: string) ⇒ string>, context: Record<string, string>): string: Compiles config with custom processor functions, renders one rule with initial context values, and releases the compiled ruleset.

Parsing and rendering failures are thrown as JavaScript exceptions with the same messages returned by the Rust renderer.

Generated TypeScript Declarations

/* tslint:disable */
/* eslint-disable */

/**
 * JavaScript-facing load-once renderer for Copperlace configuration.
 */
export class Copperlace {
    free(): void;
    [Symbol.dispose](): void;
    /**
     * Compiles a configuration string into a renderer that can be reused.
     */
    constructor(config: string);
    /**
     * Renders a named rule from the loaded config.
     */
    render(rule: string): string;
    /**
     * Renders a named rule with initial context values.
     */
    renderWithContext(rule: string, context: any): string;
    /**
     * Compiles a configuration string with custom processor functions.
     */
    static withProcessors(config: string, processors: any): Copperlace;
}

/**
 * Renders one rule from a configuration string.
 */
export function renderString(config: string, rule: string): string;

/**
 * Renders one rule from a configuration string with initial context values.
 */
export function renderStringWithContext(config: string, rule: string, context: any): string;

/**
 * Renders one rule from a configuration string with custom processor functions.
 */
export function renderStringWithProcessors(config: string, rule: string, processors: any): string;

/**
 * Renders one rule from a configuration string with custom processors and initial context.
 */
export function renderStringWithProcessorsAndContext(config: string, rule: string, processors: any, context: any): string;

export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;

export interface InitOutput {
    readonly memory: WebAssembly.Memory;
    readonly __wbg_copperlace_free: (a: number, b: number) => void;
    readonly copperlace_new: (a: number, b: number) => [number, number, number];
    readonly copperlace_render: (a: number, b: number, c: number) => [number, number, number, number];
    readonly copperlace_renderWithContext: (a: number, b: number, c: number, d: any) => [number, number, number, number];
    readonly copperlace_withProcessors: (a: number, b: number, c: any) => [number, number, number];
    readonly renderString: (a: number, b: number, c: number, d: number) => [number, number, number, number];
    readonly renderStringWithContext: (a: number, b: number, c: number, d: number, e: any) => [number, number, number, number];
    readonly renderStringWithProcessors: (a: number, b: number, c: number, d: number, e: any) => [number, number, number, number];
    readonly renderStringWithProcessorsAndContext: (a: number, b: number, c: number, d: number, e: any, f: any) => [number, number, number, number];
    readonly __wbindgen_malloc: (a: number, b: number) => number;
    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
    readonly __wbindgen_exn_store: (a: number) => void;
    readonly __externref_table_alloc: () => number;
    readonly __wbindgen_externrefs: WebAssembly.Table;
    readonly __externref_table_dealloc: (a: number) => void;
    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
    readonly __wbindgen_start: () => void;
}

export type SyncInitInput = BufferSource | WebAssembly.Module;

/**
 * Instantiates the given `module`, which can either be bytes or
 * a precompiled `WebAssembly.Module`.
 *
 * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
 *
 * @returns {InitOutput}
 */
export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;

/**
 * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
 * for everything else, calls `WebAssembly.instantiate` directly.
 *
 * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
 *
 * @returns {Promise<InitOutput>}
 */
export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;