001/*
002 * Copyright 2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.revetsec.json;
018
019import org.jspecify.annotations.NonNull;
020
021import javax.annotation.concurrent.Immutable;
022
023/**
024 * An immutable JSON value (RFC 8259): exactly one of {@link JsonObject}, {@link JsonArray}, {@link JsonString},
025 * {@link JsonNumber}, {@link JsonBoolean} or {@link JsonNull}.
026 * <p>
027 * The permitted subtypes are frozen within a major version, so an exhaustive {@code instanceof} chain or, on newer
028 * Java releases, a pattern {@code switch} over them stays exhaustive.
029 * <p>
030 * <strong>Invariants.</strong> Every value is immutable and holds no {@code null}. Its strings and member names are
031 * well-formed UTF-16 (no unpaired surrogate). It nests at most 64 deep, where a scalar or an empty container has
032 * depth 1 and any other container is 1 deeper than its deepest child (member names add nothing). A number has at most
033 * 4,096 significant digits and an adjusted decimal exponent of magnitude at most 100,000. The factories reject a
034 * {@code null} with {@link NullPointerException} and anything else outside these invariants with
035 * {@link IllegalArgumentException}, so no content can make {@link #toJson()}, {@code equals} or {@code hashCode}
036 * throw, and none of them recurses more than 64 levels deep.
037 * <p>
038 * <strong>Cost.</strong> {@code hashCode} never walks nested values: containers compute theirs once, at construction.
039 * A value may hold the same instance in several places, and {@link #toJson()} and {@code equals} then visit it once
040 * per occurrence, so their work, and the length of the JSON text, follow the value's expanded tree, not the number of
041 * objects it holds. A value that nests one instance repeatedly can therefore be far larger than its objects: its
042 * {@link #toJson()} can run out of memory, and {@code equals} against a copy built separately can take exponential
043 * time. A value parsed from JSON text is always a tree, so its cost is proportional to that text.
044 * <p>
045 * <strong>Equality.</strong> Numbers compare by numeric value ({@code 1}, {@code 1.0} and {@code 1E0} are equal),
046 * objects compare their members by name regardless of order, arrays compare element by element in order, and strings
047 * and member names compare exactly, with no case folding or Unicode normalization. {@code hashCode} is consistent
048 * with {@code equals} but not resistant to collisions: strings use {@link String#hashCode()}, containers combine
049 * their contents' hashes, and no value type is {@link Comparable}. So a {@code HashMap} or {@code HashSet} keyed by
050 * values that someone else chooses can degrade to quadratic time.
051 * <p>
052 * <strong>Rendering.</strong> {@code toString()} never shows content: it renders {@code SimpleName{...=<redacted>}},
053 * so a value that holds a secret or personal data is safe to log. {@link #toJson()} is the method that emits
054 * content.
055 *
056 * @author <a href="https://www.revetkn.com">Mark Allen</a>
057 * @since 1.0.0
058 */
059@Immutable
060public sealed interface JsonValue permits JsonObject, JsonArray, JsonString, JsonNumber, JsonBoolean, JsonNull {
061        /**
062         * Serializes this value as compact JSON text: no insignificant whitespace, members in insertion order, and numbers
063         * in the canonical form of {@link java.math.BigDecimal#toString()} ({@code 1e2} becomes {@code 1E+2}).
064         * <p>
065         * Strings escape only what JSON requires: the quotation mark, the reverse solidus and the control characters
066         * U+0000 to U+001F, using the two-character escapes where they exist. Every other character, U+2028 and U+2029
067         * included, is written as itself.
068         * <p>
069         * Unlike {@code toString()}, the result contains every string and number this value holds. It is not the text a
070         * value was parsed from, so never verify a signature over it.
071         *
072         * @return the JSON text
073         * @since 1.0.0
074         */
075        @NonNull String toJson();
076}