js-message

Protocol convention

Two familiar keys. Neither forced.

type names a signal and data carries its payload, but js-message copies what exists instead of imposing a schema. Native JSON serialization omits missing values.

js-message works with bundlers and without a bundler. Bundlers resolve bare imports normally; native browser ESM uses a standard import map with no build or transpilation step.

The envelope

{
    "type": "inventory.changed",
    "data": {
        "sku": "A-104",
        "available": 8
    }
}

type usually chooses the route or event. data usually carries the payload. Either may be absent, and js-message does not impose a vocabulary or schema inside either value. Applications can layer validation above this transport convention.

{ "type": "ping" }

A payload-free signal loads with data === undefined and serializes without a dummy data key.

What load() does

InputOutcome
JSON string with any available message fieldsParsed and assigned
Buffer, boxed string, typed view, or other JSON-coercible textNative text coercion, then parsing
Existing plain objectAvailable fields assigned by reference
Field omittedThe corresponding instance field becomes undefined.
Extra object keyAccessible on the input but excluded from normalized serialization.
Malformed JSON textRecoverable error message whose live err is a SyntaxError.
Null or uncoercible inputRecoverable error message whose live err is a TypeError.
Normalization is not validation.

If an application requires type, data, or a payload schema, validate that policy above js-message.

Normalization rules

  • Extra keys in loaded input are ignored when the message is serialized.
  • Object input keeps the original data reference; js-message does not clone payloads.
  • Missing type or data fields assign undefined for compatibility.
  • Direct assignment to either field is unrestricted.
  • JSON uses native JSON.stringify behavior, including omission, conversion, and errors.
  • A later valid load() replaces an earlier error state, so one instance can recover.
Keep payloads wire-safe.

If a message must cross JSON, prefer strings, numbers, booleans, null, arrays, and plain objects. Cycles and BigInt make native serialization throw.

See exact API behaviorApply the contract