Units

Units are named collections of pure functions, available globally across all components and callable directly from bind expressions and text interpolations. Define a utility once, use it anywhere.

Why Units Exist

Utility functions belong in one place, not scattered across every component that needs them. Units let you define formatting helpers, math operations, or string utilities once and call them from any component's template — without adding methods to individual abstractions just to make them reachable.

This is needed because WakaPAC's expression parser runs in an isolated scope: it evaluates bind expressions and text interpolations against the component's abstraction, not the JavaScript global scope. Units are the deliberate bridge — a clean, explicit way to expose shared functions to templates without opening the parser to arbitrary global access.

How Units Work

Units follow the Pascal uses convention: each unit defines its own namespace, and components can opt in to flat access via data-pac-uses. A unit lives in its own JS file and is registered on the page via wakaPAC.use():

<script src="waka-unit-math.js"></script>
<script>
    wakaPAC.use(wakaMath);
</script>

Namespaced Calls

Once registered, a unit's functions are available in any bind expression or text interpolation using UnitName.function() syntax. No component-level declaration is required.

{{ Math.round(price) }}
{{ StringUtils.capitalize(name) }}

Flat Calls via data-pac-uses

Declare data-pac-uses on a component container to import a unit's functions into its flat namespace, dropping the unit prefix entirely. Useful when a unit is used heavily throughout a component's template.

<div data-pac-id="myComponent" data-pac-uses="StringUtils">
    {{ truncate(title, 50) }}
    {{ capitalize(name) }}
</div>

Import multiple units by separating their names with commas:

<div data-pac-id="myComponent" data-pac-uses="StringUtils, WakaMath">
    {{ truncate(title, 50) }}
    {{ round(price) }}
</div>

Variable Shadowing

A data property on the abstraction takes precedence over a registered unit of the same name. If the abstraction defines a StringUtils property, StringUtils.truncate() in a template resolves to that property — not the unit.

// Abstraction with a property named 'StringUtils'
{
    StringUtils: {
        truncate: () => 'I am a data property'
    }
}

// In template: StringUtils.truncate() → calls the data property, not the unit

WakaPAC logs a console warning when a data property shadows a registered unit name, making the conflict easy to diagnose.

Writing a Unit

Unit functions receive pre-evaluated plain JavaScript values as arguments — no toolkit knowledge required. Wrap the unit in an IIFE, assign it to window, and implement createPacPlugin to return the unit's name and functions:

(function() {
    "use strict";

    window.MyUnit = {
        createPacPlugin(pac, options = {}) {
            return {
                name: 'MyUnit',
                functions: {
                    double: (n) => n * 2,
                    greet: (name) => 'Hello, ' + name + '!'
                }
            };
        }
    };

})();

Then register it on the page after loading the unit file:

wakaPAC.use(MyUnit);

Units that require configuration accept an options object as a second argument to wakaPAC.use(). The options are forwarded to createPacPlugin as the second parameter:

wakaPAC.use(DateUtils, { locale: 'nl-NL' });

Using Units as Helper Libraries

Units can also be used as imperative helper libraries within component methods, not just in templates. Call wakaPAC.unit() to retrieve a unit's function set by name or by library reference — both forms return the same object.

const cu = wakaPAC.unit('CollectionUtils');
const cu = wakaPAC.unit(CollectionUtils);   // equivalent

The returned object is the same functions object the unit exposes to templates, so all functions are immediately available:

wakaPAC('#myComponent', {
    init() {
        const str = wakaPAC.unit('StringUtils');
        console.log(str.truncate(this.title, 50));
        console.log(str.slug(this.name));
    }
});

Returns null if the unit name is not registered.

Supplied Units

WakaPAC ships with Stdlib built in and a set of optional unit files for common use cases. Optional units are standalone files that must be loaded and registered explicitly.

Stdlib

General-purpose utility functions under the Stdlib namespace. Stdlib is built into wakapac.js and registered automatically — no separate file or wakaPAC.use() call required.

Math (waka-unit-math.js)

Exposes common mathematical operations under the Math namespace.

wakaPAC.use(WakaMath);

StringUtils (waka-unit-stringutils.js)

Exposes common string operations under the StringUtils namespace.

wakaPAC.use(StringUtils);

DateUtils (waka-unit-dateutils.js)

Exposes date formatting, arithmetic, and comparison operations under the DateUtils namespace. Backed entirely by the native Intl API — no external libraries required. Accepts an optional locale at registration time; defaults to the browser's locale.

wakaPAC.use(DateUtils);                        // browser default locale
wakaPAC.use(DateUtils, { locale: 'nl-NL' });   // explicit locale

All functions accept a Date object, a numeric timestamp, or a date string. Invalid or missing input returns '' or null rather than throwing.

TypeUtils (waka-unit-typeutils.js)

Exposes type checking and type coercion functions under the TypeUtils namespace. Useful in bind conditions where typeof and strict equality checks are not available in template expressions.

wakaPAC.use(TypeUtils);

PhpUtils (waka-unit-phputils.js)

Exposes a curated set of PHP-style utility functions under the PhpUtils namespace. Functions follow PHP naming conventions and signatures. in_array always uses strict comparison (===).

wakaPAC.use(PhpUtils);

NumberUtils (waka-unit-numberutils.js)

Exposes number formatting operations under the NumberUtils namespace. Backed entirely by the native Intl API — no external libraries required. Accepts an optional locale at registration time; defaults to the browser's locale.

wakaPAC.use(NumberUtils);                        // browser default locale
wakaPAC.use(NumberUtils, { locale: 'nl-NL' });   // explicit locale

CollectionUtils (waka-unit-collectionutils.js)

Exposes array and collection operations under the CollectionUtils namespace. Key paths support dot-notation for nested property access (e.g. 'address.city').

wakaPAC.use(CollectionUtils);

RegexUtils (waka-unit-regexutils.js)

Exposes regular expression operations under the RegexUtils namespace. Patterns are parsed and cached on first use — no performance cost on repeated evaluations across render cycles.

wakaPAC.use(RegexUtils);

Patterns can be plain strings or slash-delimited with flags:

'foo'        // plain pattern, no flags
'/foo/i'     // case-insensitive
'/^\d+$/m'   // anchored, multiline

ColorUtils (waka-unit-colorutils.js)

Exposes color manipulation functions under the ColorUtils namespace. All functions accept hex color strings in #rgb or #rrggbb format and return empty string on invalid input rather than throwing.

wakaPAC.use(ColorUtils);

Blend amounts are fractional values between 0 and 1, where 0 leaves the color unchanged and 1 produces the pure target color (white for lighten, black for darken).

EscapeUtils (waka-unit-escapeutils.js)

Exposes string escaping and sanitization functions under the EscapeUtils namespace. Useful when inserting user-supplied content into HTML output, regular expressions, or URL query strings. null and undefined are coerced to an empty string rather than the literal text "null".

wakaPAC.use(EscapeUtils);

Math3D (waka-unit-math3d.js)

Exposes 4×4 matrix math, 3-component vector operations, and quaternion support under the Math3D namespace. All matrices are column-major Float32Array instances (16 elements), compatible with gl.uniformMatrix4fv() without transposing. Vectors are plain number[] arrays [x, y, z]. Quaternions are plain number[] arrays [x, y, z, w].

wakaPAC.use(Math3D);

// Retrieve in a component method
const m = wakaPAC.unit(Math3D);

// Build an MVP matrix
const mvp = m.mul(m.perspective(fov, aspect, near, far),
            m.mul(m.translation(0, 0, -4),
            m.mul(m.rotX(rx), m.rotY(ry))));
gl.uniformMatrix4fv(uMVP, false, mvp);

// Normal matrix for lighting (corrects normals under non-uniform scale)
const normalMatrix = m.transpose(m.invert(modelMatrix));
gl.uniformMatrix4fv(uNormal, false, normalMatrix);

// Smooth rotation via quaternion slerp
const q = m.quatSlerp(qA, qB, t);
gl.uniformMatrix4fv(uRot, false, m.fromQuat(q));

MAT4 — 4×4 matrix operations

VEC3 — 3-component vector operations

QUAT — quaternion operations

Quaternions are [x, y, z, w] arrays where (x, y, z) is the imaginary vector part and w is the real scalar. Unit quaternions (length = 1) represent 3D rotations without gimbal lock.