JavaScript in schemas

JavaScript in schemas lets you embed ES module source in a property's default, @read, @write, @validate, or @computed, and in a Method's implementation. The server evaluates the module on every write or read in an isolated context, sharing the request budget with Sessel. The same source is also browser-runnable, so a binding may also execute client-side under the future browser-side schema runtime.

When to reach for it

Reach for a JavaScript binding when the logic is more naturally expressed as a small ES module than a Sessel expression — for example, when reusing a familiar JavaScript idiom for string normalisation, when the same source needs to run unchanged on the server and (later) in the browser, or when the binding needs to construct schema instances via the pagelove:schema import.

JavaScript authors the default slot, the three pipeline slots (@read, @write, @validate), the schema-level @validate slot, computed properties (@computed), and method bodies (implementation). Other expression slots accept Sessel only at present: constraints, mutation handlers, HTTP queries, and e:-attribute expression bindings in SSPI templates. Group constraints and shape constraints are not expressions in either language — they are declarative Microdata and CSS selector forms.

Shape

A JavaScript binding is a typed Microdata item with itemtype="https://pagelove.org/JavaScript/Module" placed in a property's default, @read, @write, or @validate slot. Its source child carries the ES module text, conventionally inside a <script type="module"> so the same string is also browser-runnable.

<div itemprop="default" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default () => String(Math.floor(100 + Math.random() * 500));
  </script>
</div>

The dispatcher selects the language by the itemtype URL of the typed item, never by <script type>. The <script> tag is a browser-execution affordance, not a server-data signal.

The export default contract

The module must have a default export, and that export must be a function — arrow or function form. The server:

1. Evaluates the module in a fresh context.
2. Reads the default export off the module namespace.
3. Verifies it is a function.
4. Calls it with this bound to the in-progress instance and one positional argument, context.
5. Converts the return value back to a dombase value.

ES modules always run in strict mode, so arrow functions do not bind their own this. A binding that needs to read this must use a function form:

export default function() { return this.firstname; }

A module with no default export, or a default export that is not a function, fails with the shape variant.

Slot semantics

For property-level @read, @write, and @validate, the first argument is the pipeline value, not the owning instance. For default, schema-level @validate, and @computed, this is the instance — so these must use a function form to read this (an arrow function in a strict-mode ES module does not bind its own this). Method bodies also bind this to the owning instance (the Class constructor for static methods) — see Method bodies below.

Computed properties (@computed)

An @computed slot makes a property's value always derived from a binding, with no value stored for it. The binding runs on every read; assigning to the property is rejected, since there is nothing to assign to.

<div itemprop="@computed" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default function() { return this.firstName + " " + this.lastName; }
  </script>
</div>

this is bound to the owning instance (a function form is required to read it). If a property declares both @computed and @read, @computed wins and @read never runs for it. A legacy, Sessel-only shorthand — an @read slot whose typed item is the bare https://pagelove.org/Sessel type — is also still recognized as a computed property for backward compatibility; new schemas should prefer @computed. See Property for the full behavior, including the legacy form.

Method bodies

A Method's implementation slot accepts a JavaScript module the same way a property binding does:

<div itemprop="property" itemscope itemtype="https://pagelove.org/Method">
  <meta itemprop="name" content="greet">
  <div itemprop="parameter" itemscope itemtype="https://pagelove.org/Parameter">
    <meta itemprop="name" content="greeting">
  </div>
  <div itemprop="implementation" itemscope itemtype="https://pagelove.org/JavaScript/Module">
    <script itemprop="source" type="module">
      export default function(greeting) { return greeting + ", " + this.name + "!"; }
    </script>
  </div>
</div>

this is bound to the calling object — the schema instance for an instance method, or the Class constructor for a static method. Parameters are forwarded positionally, in the method's declared parameter order (Sessel implementations instead read each parameter by name). A method body may be async; the engine drives its returned Promise to settlement the same way an async default export settles.

Method bodies also dispatch when a schema method is invoked through page composition — a namespaced method element (<ns:method>) or an ns:method="…" attribute. There, this is the host element the method was dispatched on (read-only), arguments bind by name from the dispatch element's attributes (rather than positionally), an ambient read-only document is available, and the return value is spliced into the page. See Method Elements for the composition-side contract, and Methods for the schema-level declaration.

A method body dispatches in a third context too: when the method is called from another server-side expression — a trigger's action, a processor, a mutation handler, or a nested method call made by another method (whether that caller is written in Sessel or JavaScript). Here the call behaves like a direct instance.method(...) call: arguments are forwarded positionally in declared order, this is the receiver, and the return value is the method's value. A read-only document global is available only when the receiver is an element; a typed schema instance receives no document global and operates on this.

In this third context the method also has full access to the shared Context: it can read ambient entries such as Context.request, and any Context.foo = … assignment it makes is written back to the pass's Context — the same Context a Sessel method mutates in the same place — so a processor or trigger that reads Context afterwards observes the change. (Reading per-user request identity marks the response as user-specific, just as it does in composition.)

Whichever way a method is dispatched — through page composition (<ns:method> splicing its return into the page) or from another server-side expression — when it returns a typed schema instance it builds, that instance is treated exactly as new SchemaName { … }: its schema's @default values are filled in for any properties left unset, and it is validated against the schema (missing a required property with no default, or a wrong type, raises an error). So a method can construct and return an instance and rely on the same defaults and validation Sessel construction gives — you don't have to set defaulted properties yourself.

this and context for default

this — the in-progress instance

this is a read-only plain JS object view of the element being created. It exposes the schema-declared property keys that are already set — fields supplied by the client on the write, or fields set earlier in construction. Mutations to this inside a default expression are not preserved.

A default on one property may not read the value of another property whose default is also being computed in the same creation. Reading such a field returns undefined. Cross-property default ordering is not part of the public schema contract.

context — request and host information

context is a plain JS object passed as the first positional argument. The first cut carries a minimal set of well-known keys:

Authors must read only the keys they need and not enumerate or rely on the exact set. Future revisions may add keys.

The document global

Separately from context, a default expression also has access to a document global — a live view of the in-progress element that supports the same DOM methods as the JavaScript DOM API, including mutations (document.querySelector(...), appending or removing elements, and so on). Any changes made through document are kept: they're applied to the element being created.

Other binding kinds that also receive a document global (for example @write bindings) get a read-only version — calling a mutating method throws.

Chaining order

When a property has pipeline bindings at multiple levels of a schema inheritance chain, stages are chained:

Pipeline chains can mix Sessel and JavaScript freely across the inheritance hierarchy. A parent's Sessel stage feeds a child's JavaScript stage, and vice versa, in the order above.

Importing schemas

A schema import uses the schema URL as the module specifier, with a fixed type import attribute of "https://pagelove.org/Schema":

import Note from "https://moodboard.pagelove.org/Note" with { type: "https://pagelove.org/Schema" };

The schema URL is an identifier, not a fetchable URL. The module loader resolves the import at evaluation time by looking up the schema in the host's schema cache. An unknown schema fails with the unknown-schema variant.

Each import yields a JavaScript class with the schema's short name (the last path segment of the itemtype URL). The class is synthesised at evaluation time and supports construction, property access, instanceof, and method dispatch.

All other import specifiers (relative paths, bare specifiers, HTTP URLs) are rejected with the import-not-allowed variant. There is no pagelove:host module.

Working with imported classes

Schemas inheriting from https://pagelove.org/Map produce classes that extend Map, with keys, values, entries, and merge exposed. Undeclared property reads fall through to the Map backing store.

Supported language features

Supported:

• ES2020+ syntax: const/let, arrow and function forms, destructuring, spread/rest, template literals, default parameters, async/await at the expression level, optional chaining, nullish coalescing, numeric separators.
• Standard built-in globals: Math, Date, JSON, String, Number, Array, Object, Map, Set, RegExp, Symbol, and the other ECMAScript built-ins.
• Template literals and tagged templates.

Not supported:

• import statements other than pagelove:schema.
• Host I/O globals: no fetch, no process, no require, no filesystem or environment access.
• Network and timers: setTimeout and setInterval are not available.

Math.random() and Date.now() are permitted and return legitimately different values on the server and the browser. Bindings commit logic over inputs, not clock or RNG agreement; the server's value is what gets stored.

Resource limits

Every evaluation runs under a per-request budget. In production the budget is read from the host's https://pagelove.org/TransactionBudget Microdata, shared with Sessel. A request touching one Sessel binding and one JavaScript binding sees a single shared budget, not two competing ones.

Errors

Every failure is rendered to the client as an HTML Microdata document of type https://pagelove.org/BindingFailure, nested inside the https://pagelove.org/SchemaViolation envelope.

The rendered failure carries at minimum:

<div itemscope itemtype="https://pagelove.org/BindingFailure">
  <meta itemprop="language" content="https://pagelove.org/JavaScript/Module">
  <meta itemprop="variant" content="threw">
  <p itemprop="message">TypeError: Cannot read properties of undefined (reading 'foo')</p>
  <pre itemprop="stack">    at default (eval:2:17)</pre>
</div>

The stack property is present for threw when the engine provided one and absent otherwise. Sessel bindings produce structurally identical BindingFailure items with a different language value.

Tracing

Every JavaScript evaluation produces an OpenTelemetry-compatible span named dombase_js.evaluate:

A child span dombase_js.compile wraps the compile step on the first use of a given source on a thread. Cross-language Sessel calls from within JavaScript nest as children of the dombase_js.evaluate span.

Marshalling

Values flow between dombase and JavaScript at every binding boundary:

First-cut exclusions

The following are out of scope for the current cut. Each is either a deferred feature or an interim limitation that will be lifted without breaking existing bindings:

• Imports other than pagelove:schema. No pagelove:host module. No relative or HTTP imports.
• Constraints, mutation handlers, HTTP queries, and e:-attribute expression bindings in SSPI templates. All Sessel-only at present.
• Cross-property this access on default. A default cannot read another property whose default is also being computed on the same creation.
• Browser-side execution of these bindings. The source-level contract that makes browser-side execution possible is committed; the runtime that calls it client-side is a future spec.

Examples

Random coordinate default

<div itemprop="default" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default () => String(Math.floor(100 + Math.random() * 500));
  </script>
</div>

Timestamp default reading context

<div itemprop="default" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default function(context) {
      return `created at ${new Date().toISOString()}`;
    }
  </script>
</div>

Normalise on write

<div itemprop="@write" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default (val) => typeof val === 'string' ? val.trim().toLowerCase() : val;
  </script>
</div>

Format on read

<div itemprop="@read" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default (val) => typeof val === 'string' ? val.toUpperCase() : val;
  </script>
</div>

Validate at persistence

<div itemprop="@validate" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default (val) => typeof val === 'string' && val.includes('@');
  </script>
</div>

Default that constructs a schema instance

<div itemprop="default" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    import Note from "https://moodboard.pagelove.org/Note" with { type: "https://pagelove.org/Schema" };
    export default () => new Note({ title: "untitled", x: 0, y: 0 });
  </script>
</div>

Computed property combining two fields

<div itemprop="@computed" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default function() { return this.firstName + " " + this.lastName; }
  </script>
</div>

Method body using a parameter and this

<div itemprop="implementation" itemscope itemtype="https://pagelove.org/JavaScript/Module">
  <script itemprop="source" type="module">
    export default function(greeting) { return greeting + ", " + this.name + "!"; }
  </script>
</div>

See also

• JavaScript DOM API — the DOM subset (document, querySelector, createElement, classList, …) a JavaScript binding can use to traverse and build markup
• Property — the slot in which default, @read, @write, @validate, and @computed are declared
• Methods — the schema-level declaration a method body's implementation slot belongs to
• Method Elements — invoking a method during page composition
• Resolvers — @read and @write pipeline semantics shared with Sessel
• Schema — inheritance, which determines pipeline chain order
• Sessel — the peer binding language; both share the same slots and error envelope
• Schema definitions in HTML — the client-side counterpart that runs JavaScript modules in the browser