@metreeca/qest - v0.9.2
    Preparing search index...

    Module state

    Resource state management.

    Defines types for describing resource states and partial updates in REST/JSON APIs, using native JSON types with localised text support:

    • Resource — Complete resource state (HTTP GET/PUT)
    • Patch — Partial resource updates (HTTP PATCH)
    • Values — Property value sets
    • Value — Individual property values
    • Literal — Primitive data values
    • Reference — IRI resource references
    • Local — Language-tagged text map (single-valued)
    • Locals — Language-tagged text map (multi-valued)
    • Indexed — Key-indexed value container

    Resource Operations

    A Resource is a property map describing the state of a resource:

    GET https://example.com/products/42

    {
      "id": "/products/42",
      "name": "Widget",
      "price": 29.99,
      "available": true
    }

    Resources may include an IRI property mapped to @id in the application-defined JSON-LD @context, identifying the resource globally. This property is usually named id, but the mapping is arbitrary. A state without such a property represents an anonymous (blank) node—useful for nested structures that don't need their own identity:

    {
      "id": "/products/42",
      "name": "Widget",
      "price": 29.99,
      "dimensions": {
        "width": 10,
        "height": 5,
        "depth": 3
      }
    }

    Resources can link to other resources using IRI references or embedded descriptions. IRI references identify a resource without describing its state, while embedded descriptions include the linked resource's properties:

    // IRI references: compact form linking to external resources

    ({
      "id": "/products/42",
      "name": "Widget",
      "price": 29.99,
      "vendor": "/vendors/acme",
      "categories": ["/categories/electronics", "/categories/home"]
    })

    // Embedded descriptions: expanded form with linked resource properties

    ({
      "id": "/products/42",
      "name": "Widget",
      "price": 29.99,
      "vendor": {
        "id": "/vendors/acme",
        "name": "Acme Corp"
      },
      "categories": [
        { "id": "/categories/electronics", "name": "Electronics" },
        { "id": "/categories/home", "name": "Home" }
      ]
    })

    A Resource serves as payload for HTTP POST operations:

    POST https://example.com/products/

    {
      "name": "Gadget",
      "price": 49.99,
      "categories": ["electronics", "home"],
      "available": true
    }
    Important

    Nested resource states containing properties beyond the resource identifier are only accepted if explicitly declared as embedded in the application-defined data model; non-embedded nested resources with additional properties will be rejected during validation.

    // Using IRI references (always valid)

    ({
      "name": "Gadget",
      "price": 49.99,
      "vendor": "/vendors/acme"
    })

    // Using nested states with only the identifier property (always valid)

    ({
      "name": "Gadget",
      "price": 49.99,
      "vendor": {
        "id": "/vendors/acme"
      }
    })

    // Using nested states with additional properties (must be declared as embedded)

    ({
      "name": "Gadget",
      "price": 49.99,
      "vendor": {         // requires 'vendor' declared as embedded
        "id": "/vendors/acme",
        "name": "Acme Corp"
      }
    })

    A Resource also serves as payload for HTTP PUT operations:

    PUT https://example.com/products/42

    ({
      "name": "Widget",
      "price": 79.99,
      "categories": ["electronics", "premium"]
      // available       // not included → deleted
    })
    Important

    State replacement is total — properties not included in the state are removed from the resource; empty arrays are treated as property deletions, following set semantics where an empty set is equivalent to absence.

    A Patch serves as payload for HTTP PATCH operations. Properties can be set to new values or deleted using null; unlisted properties remain unchanged:

    PATCH https://example.com/products/42

    ({
      "price": 39.99,         // update
      "description": null,    // delete
      "available": true,      // update
      "categories": []        // delete
    })
    Important

    Empty arrays are treated as property deletions, following set semantics where an empty set is equivalent to absence.

    HTTP DELETE operations remove the resource at the request URL (no payload is required):

    DELETE https://example.com/products/42

    Value Types

    Each property in a resource state or patch holds Values:

    • a single Value
    • a Local single-valued language-tagged text map
    • a Locals multi-valued language-tagged text map
    • an array representing a set of values

    Additionally, properties can hold an Indexed container, mapping arbitrary keys to Values.

    A Value can be:

    • Literal: primitive data (boolean, number, string)
    • Reference: IRI identifying a linked resource
    • Resource: nested resource state
    Important

    Arrays follow set semantics — duplicates are ignored, ordering is immaterial, and empty arrays are treated as absent values. This aligns with JSON-LD's multi-valued property model.

    An IRI (Internationalized Resource Identifier) is a globally unique string identifying a resource on the web. IRIs enable entity linking by referencing resources without embedding their full state. Properties mapped to @id in the application-provided JSON-LD @context expect IRI values, establishing relationships between resources across systems and domains.

    Note

    Data structures require absolute IRIs. Codec functions (encodeResource, decodeResource, etc.) convert between absolute and internal (root-relative) forms for serialization.

    A Literal maps directly to JSON primitives (boolean, number, string). Dates, times, and other structured values are represented as strings in standard formats (e.g., ISO 8601). Application-level @context objects can declare datatype coercion rules for JSON-LD processing.

    Localised Text

    For multilingual content, use Local or Locals language-tagged text maps. Tags follow RFC 5646 (e.g., en, de-CH, zh-Hans):

    // single value per language

    ({
      "en": "Universal Widget",
      "fr": "Widget Universel",
      "de": "Universelles Widget"
    })

    // multiple values per language

    ({
      "en": ["tool", "gadget", "utility"],
      "fr": ["outil", "gadget"]
    })
    Important

    The @none key for non-localised values is not supported; for mixed content use string | Local or readonly string[] | Locals union types, or the zxx tag.

    Type Aliases

    Resource

    Linked data resource state.

    Patch

    Partial resource state update.

    Values

    Model value set.

    Value

    Model value.

    Literal

    Literal value.

    Reference

    Resource reference.

    Local

    Single-valued language-tagged map for internationalised text.

    Locals

    Multi-valued language-tagged map for internationalised text.

    Guards

    Type guards for runtime validation of resource and value types.

    isResource

    Checks if a value is a Resource.

    isPatch

    Checks if a value is a Patch.

    isValues

    Checks if a value is a Values.

    isValue

    Checks if a value is a Value.

    isLiteral

    Checks if a value is a Literal.

    isReference

    Checks if a value is a Reference.

    isLocal

    Checks if a value is a Local.

    isLocals

    Checks if a value is a Locals.

    Codecs

    Functions for converting between serialized and structured representations.

    encodeResource

    Encodes a resource state as a JSON string.

    decodeResource

    Decodes a resource state from a JSON string.

    encodePatch

    Encodes a patch as a JSON string.

    decodePatch

    Decodes a patch from a JSON string.

    Settings

    Member Visibility

    On This Page

    Resource OperationsValue Types
    Type Aliases
    Guards
    Codecs