1.1 Features

• Customizable: Provides the ability to initiate custom server requests for dynamically receiving user interface content, enabling fine-grained control over request structure and behavior.
• Memory Preserving: Significantly reduces client-side file sizes by offloading rendering logic to the server, minimizing front-end resource requirements.
• Standards-Based (Fetch API): Utilizes the modern Fetch API for performing network requests, offering a standardized, promise-based alternative to legacy XMLHttpRequest.
• Server-Oriented: Designed to prioritize server-driven rendering workflows, enabling UI generation through declarative markup with minimal JavaScript involvement.
• High-Volume DOM Generation: Supports the efficient creation of large quantities of DOM nodes from a single template, enabling scalable component rendering both on the server and the client.
• Simplicity: Allows ready-to-render UI content to be retrieved from the server using concise, familiar object notation requiring minimal code.
• XSS Protection: Integrates HTML sanitization using DOMPurify, ensuring the safe handling of incoming server-generated markup to mitigate cross-site scripting (XSS) vulnerabilities.
• Flexible Integration: Capable of operating within a wide range of project types, supporting both script-based usage and dedicated markup files with the .hmpl file extension.
• JSON5 Compatibility: Provides flexible and expressive object syntax via JSON5, ensuring developer-friendly notation and leveraging a widely adopted, reliable parser.
• Compact Bundle Size: Delivers substantial functionality in a minimal bundle footprint, typically limited to a few kilobytes.

1.2 Example

import hmpl from "hmpl-js";
  
const templateFn = hmpl.compile(
  `<div>
      <button data-action="increment" id="btn">Click!</button>
      <div>Clicks: {{
        "src": "/api/clicks",
        "after": "click:#btn"
      }}</div>
  </div>`
);

const clicker = templateFn(({ request: { event } }) => ({
  body: JSON.stringify({ action: event.target.getAttribute("data-action") })
})).response;

document.querySelector("#app").append(clicker);

2.1 compile

The compile method processes HMPL template strings into executable template functions (HMPLTemplateFunction).

const templateFn = hmpl.compile(
  `{ 
     {
       "src":"/api/test" 
     } 
   }`,
  {
    memo: true,
    autoBody: {
      formData: true
    },
    allowedContentTypes: ["text/html"],
    disallowedTags: ["script"],
    sanitize: false
  }
);

<div>
  <button data-action="increment" id="btn">Click!</button>
  <div>Clicks: {{ "src": "/api/clicks", "after": "click:#btn" }}</div>
</div>

2.2 stringify

Serializes HMPLRequestInfo objects into JSON5 strings suitable for template embedding.

const request = hmpl.stringify({
  src: "/api/test"
});
const templateFn = hmpl.compile(`{${request}}`);

Implementation notes:

• Uses JSON5 serialization for improved readability
• Maintains all original object properties
• Produces valid template syntax

3.1 RequestInit

The HMPLRequestInit interface extends the standard RequestInit with HMPL-specific properties.

const elementObj = templateFn({
  mode: "cors",
  cache: "no-cache",
  credentials: "same-origin",
  headers: {
    "Content-Type": "text/html"
  },
  redirect: "follow",
  get: (prop, value) => {},
  referrerPolicy: "no-referrer",
  body: JSON.stringify(data),
  signal: new AbortController().signal,
  integrity: "...",
  window: null,
  refferer: "about:client"
});

const elementObj = templateFn({
  get: (prop, value, requestObject) => {
    switch (prop) {
      case "response":
        if (!requestObject) console.log(requestObject);
        console.log("Response:");
        console.log(value);
        break;
      case "status":
        console.log("Status:");
        console.log(value);
        break;
    }
  }
});

const val = await new Promise((res, rej) => {
  templateFn({
    get: (prop, value, requestObject) => {
      switch (prop) {
        case "response":
          if (!value) return;
          res(value);
          break;
      }
    }
  });
});

3.2 Identification RequestInit

The HMPLIdentificationRequestInit interface associates request configurations with specific template requests via unique identifiers.

const elementObj = templateFn([
{
  id: "1",
  value: {
    mode: "cors",
    cache: "no-cache",
    credentials: "same-origin",
    headers: {
      "Content-Type": "text/html"
    },
    redirect: "follow",
    get: (prop, value) => {},
    referrerPolicy: "no-referrer",
    body: JSON.stringify(data)
  }
}]);

const templateFn = hmpl.compile(
  `{ 
     {
       "src":"/api/test" 
     } 
   }`
);
const elementObj = templateFn();

const templateFn = hmpl.compile(
  `<div>
   {
     {
       "src":"/api/test"
     }
   }
   {
     {
       "src":"/api/test"
     }
   }
</div>`
);
const elementObj = templateFn();

3.3 RequestInit Function

The HMPLRequestInitFunction enables dynamic request configuration based on execution context.

const elementObj = templateFn(({
  request: { event }
})=>{
  return {
      mode: "cors",
      cache: "no-cache",
      credentials: "same-origin",
      headers: {
        "Content-Type": "text/html",
      },
      redirect: "follow",
      get: (prop, value) => {},
      referrerPolicy: "no-referrer",
      body: new FormatData(event.target, event.submitter),
    }
});

5.1 src

The src property specifies the target URL for the request. This property is required for all request configurations.

5.2 method

The method property defines the HTTP verb for the request. Supported methods include:

• GET
• POST
• PUT
• PATCH
• DELETE

5.3 after

The after property specifies event-based request triggering using the format:

${eventType}:${selector}

5.4 repeat

The repeat property controls whether a request re-executes on subsequent trigger events:

• true: Request executes on every trigger (default)
• false: Request executes once, then removes listeners

5.5 indicators

The indicators property is intended to define the HTML content that should be rendered in response to a particular request status. This property enables authors to provide user interface feedback corresponding to specific states of a request initiated by the HMPL module.

The value of the indicators property is either a single HMPLIndicator object or an array of such objects. Each object specifies a trigger condition and associated content, representing the HTML markup to be displayed when the corresponding status is active.

The value of the content property is a string containing static HTML markup. This markup is not interpreted or extended by the HMPL module, and therefore does not support HMPL-specific syntax or dynamic bindings.

The trigger property specifies the status condition under which the associated content should be displayed. Its value may be one of the following:

The permissible values for trigger are:

• HTTP status codes within the range 400 to 599, indicating client and server errors as defined by the HTTP specification.
• The string literal "pending", representing the Promise state where a request is in progress and awaiting resolution.
• The string literal "rejected", representing a Promise rejection or a failed fetch operation.
• The string literal "error", a generic value that serves as a catch-all trigger, activated under either of the following circumstances:
  • A HTTP response with a status code between 400 and 599.
  • A "rejected" Promise state.

5.6 autoBody

The autoBody property specifies automatic generation of the body property within a HMPLRequestInit object. Its purpose is to facilitate the automatic population of request bodies from form-related user input when a request is initiated via HMPL.

The property accepts either a Boolean value or an HMPLAutoBodyOptions object, determining how the request body should be constructed.

<div>
  <form onsubmit="function prevent(e){e.preventDefault();};return prevent(event);" id="form">
    <div class="form-example">
      <label for="name">Enter your email:</label>
      <input type="text" name="email" id="email" required />
    </div>
    <div class="form-example">
      <input type="submit" value="Subscribe!" />
    </div>
  </form>
  {
    {
      "src":"/api/subscribe",
      "after":"submit:#form",
      "autoBody":true
    }
  }
</div>

If the value of autoBody is true, the module automatically generates a FormData instance using the associated SubmitEvent target element and its submitter.

When automatic generation is active, the body property in the resulting HMPLRequestInit will be assigned a FormData instance constructed as follows:

const body = new FormData(event.target, event.submitter);

It is important to note that automatic generation will only overwrite the existing body property if the HMPLRequestInit object is not derived from a RequestInit function. In such cases, the manually specified body value takes precedence.

5.7 memo

The memo property enables response caching for identical requests. When enabled:

• Identical requests return cached responses
• Only active when repeat is true
• Improves performance for repeated requests

The memoization process can be conceptually compared to disabling the no-cache directive in the RequestCache API, as it prevents repeated fetching of the same resource within the same runtime environment.

5.8 initId

The initId property establishes an explicit association between a request and a predefined initialization object. It references the id property of a corresponding entry in the HMPLRequestInit dictionary collection, determining the initialization parameters for the request.

The value assigned to initId may be either a string or a number, providing flexibility in identification schemes.

<div>
  {
    {
      "src": "/api/test",
      "initId": "1"
    }
  }
  {
    {
      "src": "/api/test",
      "initId": 2
    }
  }
</div>

const requestInits = [
  { id: "1", value: ... },
  { id: 2, value: ... },
];
const instance = templateFn(requestInits);

Multiple requests can reference the same initId, allowing them to share a common set of initialization options. This behavior is conceptually analogous to the use of foreign keys in relational databases, enabling reuse and normalization of request configurations.

5.9 allowedContentTypes

The allowedContentTypes property defines the list of permissible Content-Type values within the headers of HTTP responses returned from server requests. This property enables content validation and type safety when processing server responses.

The property value may be either:

• The string literal "*", indicating that all content types compatible with the text method are allowed.
• An array of string values, each representing an explicitly permitted Content-Type.

If the array is empty, behavior is equivalent to using "*" — all types supporting the text method are permitted.

{
  {
    "allowedContentTypes": [
      "application/json; charset=utf-8",
      "text/plain"
    ]
  }
}

The default value of this property is ["text/html"].

    48 65 6C 6C 6F 2C 20 77 6F 72 6C 64 21
        

For additional guidance on server-side configuration and content type handling, refer to the Server Configuration documentation.

5.10 disallowedTags

The disallowedTags property specifies HTML elements to remove from responses. Supported tags include:

• "script"
• "style"
• "iframe"

5.11 sanitize

The sanitize property enables DOMPurify-based HTML sanitization. When enabled:

• Removes potentially malicious content
• Preserves safe HTML markup
• Executes before disallowed tag removal

6.1 HMPLRequestInit

Extends standard RequestInit with HMPL-specific properties.

interface HMPLRequestOptions {
  mode?: RequestMode;
  cache?: RequestCache;
  redirect?: RequestRedirect;
  referrerPolicy?: ReferrerPolicy;
  integrity?: string;
  referrer?: string;
  get?: HMPLRequestGet;
  body?: BodyInit | null;
  signal?: AbortSignal | null;
  window?: any;
  credentials?: RequestCredentials;
  headers?: HMPLHeadersInit;
  timeout?: number;
}

6.2 HMPLInstance

Template execution result container.

interface HMPLInstance {
  response: undefined | Element | null;
  status?: HMPLRequestStatus;
  requests?: HMPLRequest[];
}

6.3 HMPLInstanceContext

Provides execution context to request initialization functions.

interface HMPLInstanceContext {
  request: HMPLRequestContext;
}

6.4 HMPLRequest

Individual request result container.

interface HMPLRequest {
  response: undefined | Element | null | ChildNode[];
  status: number;
  id?: string;
}

6.5 HMPLRequestContext

Contains request-specific execution details.

interface HMPLRequestContext {
  event?: Event;
}

6.6 HMPLRequestGet

Property change callback signature.

type HMPLRequestGet = (prop: string, value: any, request?: HMPLRequest) => void;

6.7 HMPLRequestInfo

Template request configuration interface.

interface HMPLRequestInfo {
  src: string;
  method?: string;
  initId?: string | number;
  after?: string;
  repeat?: boolean;
  memo?: boolean;
  allowedContentTypes?: HMPLContentTypes;
  indicators?: HMPLIndicator[];
  sanitize?: HMPLSanitize;
  disallowedTags?: HMPLDisallowedTags;
  autoBody?: boolean | HMPLAutoBodyOptions;
}

6.8 HMPLCompile

Template compilation function signature.

type HMPLCompile = (
  template: string,
  options?: HMPLCompileOptions
) => HMPLTemplateFunction;

6.9 HMPLCompileOptions

Template compilation configuration.

interface HMPLCompileOptions {
  memo?: boolean;
  autoBody?: boolean | HMPLAutoBodyOptions;
  allowedContentTypes?: HMPLContentTypes;
  sanitize?: HMPLSanitize;
  disallowedTags?: HMPLDisallowedTags;
}

6.10 HMPLTemplateFunction

Executable template function interface.

type HMPLTemplateFunction = (
  options?:
    | HMPLIdentificationRequestInit[]
    | HMPLRequestInit
    | HMPLRequestInitFunction
) => HMPLInstance;

6.11 HMPLAutoBodyOptions

Automatic body generation configuration.

interface HMPLAutoBodyOptions {
  formData?: boolean;
}

6.12 HMPLInitalStatus

Union of Promise states and non-success HTTP status codes.

type HMPLInitalStatus =
  | "pending"
  | "rejected"
  | 100
  | 101
  | 102
  | 103
  | 300
  | 301
  | 302
  | 303
  | 304
  | 305
  | 306
  | 307
  | 308
  | 400
  | 401
  | 402
  | 403
  | 404
  | 405
  | 406
  | 407
  | 408
  | 409
  | 410
  | 411
  | 412
  | 413
  | 414
  | 415
  | 416
  | 417
  | 418
  | 421
  | 422
  | 423
  | 424
  | 425
  | 426
  | 428
  | 429
  | 431
  | 451
  | 500
  | 501
  | 502
  | 503
  | 504
  | 505
  | 506
  | 507
  | 508
  | 510
  | 511;

6.13 HMPLIndicatorTrigger

Valid indicator display conditions.

type HMPLIndicatorTrigger = HMPLInitalStatus | "error";

6.14 HMPLRequestStatus

Union of all possible HTTP status codes and Promise states.

type HMPLRequestStatus =
  | HMPLInitalStatus
  | 200
  | 201
  | 202
  | 203
  | 204
  | 205
  | 206
  | 207
  | 208
  | 226;

6.15 HMPLContentTypes

Content-Type restriction specification.

type HMPLContentTypes = string[] | "*";

6.16 HMPLDisallowedTag

HTML elements eligible for removal.

type HMPLDisallowedTag = "script" | "style" | "iframe";

6.17 HMPLDisallowedTags

Array of disallowed elements.

type HMPLDisallowedTags = HMPLDisallowedTag[];

6.18 HMPLSanitize

HTML sanitization toggle.

type HMPLSanitize = boolean;

6.19 HMPLIndicator

Status-specific UI definition.

interface HMPLIndicator {
  trigger: HMPLIndicatorTrigger;
  content: string;
}

6.20 HMPLHeadersInit

Header dictionary interface.

interface HMPLHeadersInit {
  [key: string]: string;
}

6.21 HMPLIdentificationRequestInit

Request initialization reference container.

interface HMPLIdentificationRequestInit {
  value: HMPLRequestInit | HMPLRequestInitFunction;
  id: string | number;
}

6.22 HMPLRequestInitFunction

Dynamic request initialization signature.

type HMPLRequestInitFunction = (
  context: HMPLInstanceContext
) => HMPLRequestInit;