Skip to content

v1.1.0 (2026-09-25)

Latest

Choose a tag to compare

@dolmen dolmen released this 25 Sep 14:03

The exported API is unchanged: no identifier has been added, removed or modified. However bugs which made Get, Set and Delete panic or silently do nothing on serialized documents are fixed, and errors are now reported consistently whatever the representation of the document. Those fixes change what some calls return: see Changed below before upgrading.

Added

  • Set and Delete decode a serialized part
    of a document lazily: only the containers on the path to the value are
    decoded, one layer at a time, and the values outside of that path are kept as
    json.RawMessage. Set and Delete may therefore leave
    []json.RawMessage or map[string]json.RawMessage containers in the
    document, which Get accepts back.

  • Partially deserialized documents are now first-class: []json.RawMessage and
    map[string]json.RawMessage are accepted by Get,
    Pointer.In, Set and
    Delete, at any level of the document, mixed with the other
    representations.

  • Documentation: the package documentation now presents the whole API;
    Get documents which values are returned as stored and which
    are returned as a deserialized copy; JSONDecoder
    documents that it is consumed.

Fixed

  • Get no longer panics (unexpected key type) when a property
    is not found in a json.RawMessage or a
    JSONDecoder document. It reports
    ErrProperty.
    Commit: 887246f.

  • Set and Delete no longer silently do
    nothing when the value to modify is inside a
    json.RawMessage: the decoded value is now stored back in
    the document. They also no longer panic when a property on the path is
    missing.
    Commit: 880a8c8.

  • Set no longer stores the JSON encoding of the
    json.Decoder struct itself ({}) when given a
    JSONDecoder as the value.
    Commit: 4a9615d.

  • Pointer.UnmarshalText no longer modifies
    the byte slice it is given, and no longer panics on some invalid escapes. The
    location it reports for a syntax error is now the invalid token instead of the
    empty pointer.
    Commit: 4f3895b.

  • Pointer.In no longer panics when the first token is
    applied to a value which is not an object or an array.
    Commit: abe215f.

  • On error, a JSONDecoder which has been read is
    replaced in the document by the raw value read from it, so the document
    remains usable.
    Commits: 4f7aba2, d88a3f0.

  • DocumentError.Error now includes the
    location, like the other error types, and stays consistent with the Ptr
    field when the error is rebased.
    Commit: 4fac752.

  • Add this CHANGELOG. Drafted by AI, but carefully edited by
    its human master.

Changed

These changes are source compatible, but code which inspects errors or uses the
value returned by Delete may need an update:

  • An error reported because a value can't be traversed
    (DocumentError) now points to that value instead of
    the location below it: Get(doc, "/a/b") where /a is a number reports
    "/a" instead of "/a/b".
    Commits: 1cf28c3, bbe5c28.

  • Get deserializes deeply the value it returns when that value
    is a json.RawMessage, a
    JSONDecoder, a []json.RawMessage or a
    map[string]json.RawMessage. The result is then a copy: modifying it does not
    modify the document. A value which is already deserialized is still returned
    as stored, so modifying it does modify the document.
    Commit: bd5a895.

  • Set rewrites every container on the path to the value as a
    map[string]interface{} or a []interface{}.
    Commit: 4a9615d.

  • Delete returns the value as it is stored in the document.
    When the container of the value is a json.RawMessage, a
    []json.RawMessage or a map[string]json.RawMessage, the value is therefore
    returned as a json.RawMessage instead of a deserialized value. Code
    type-asserting the result of Delete on a serialized document must now handle
    json.RawMessage
    (jsonptr.Get(v, "") deserializes it).
    Commit: d88a3f0.

  • Delete reports an index which is out of range, or "-",
    as a *PtrError wrapping ErrIndex
    instead of a *BadPointerError, like
    Get does.
    Commit: d88a3f0.

  • A token which is not a valid array index ("x", "01", "-1", …) is now
    reported as a *PtrError wrapping
    ErrIndex instead of a
    *BadPointerError wrapping
    ErrSyntax. An invalid escape ("~2") is still a
    *BadPointerError wrapping ErrSyntax, whatever the container. Code
    testing errors.Is(err, ErrSyntax) for an invalid index must now test
    ErrIndex.

    Commits: 58ab2dc, de73458.

Internal

  • Statement coverage of the testsuite raised from 77.9% to 96.0% ; added some
    benchmarks and fuzzing tests.

  • Tests run in parallel, and check the kind and the location of every error for
    each representation of the document.

  • Set and Delete are reimplemented as
    recursive functions which walk the document a single time.