mobx-state-tree 7.2.0 → 7.3.0

package/dist/core/type/errorFormatting.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Options that control how snapshots/values and type shapes are rendered inside
+ * type-checking error messages (see {@link setErrorFormatting}).
+ */
+export interface ErrorFormattingOptions {
+    /**
+     * When `false` (the default), error messages are rendered exactly as they
+     * always have been: the offending value is serialized to a single
+     * `JSON.stringify` line and the message is capped in length. When `true`,
+     * the value is truncated (using the limits below) and, when `indent > 0`,
+     * pretty-printed across multiple lines.
+     */
+    enabled: boolean;
+    /**
+     * Number of spaces to indent each nesting level by when pretty-printing.
+     * Use `0` to keep everything on a single line while still truncating
+     * (handy when you only want to bound the message size, not reflow it).
+     */
+    indent: number;
+    /** Strings longer than this are clipped, with a note of how many characters were omitted. */
+    maxStringLength: number;
+    /** Arrays with more than this many items are clipped, with a note of how many items were omitted. */
+    maxArrayLength: number;
+    /** Objects with more than this many keys are clipped, with a note of how many keys were omitted. */
+    maxPropertyCount: number;
+    /** Values nested deeper than this are summarized as `{…}` / `[…]`. */
+    maxDepth: number;
+}
+/**
+ * Configures how snapshots/values and type shapes are formatted inside
+ * type-checking error messages. This is **opt-in**: by default MST keeps its
+ * original single-line error formatting, so enabling this does not change
+ * behavior for anyone who doesn't call it.
+ *
+ * The given options are merged over the current ones, so you can set only the
+ * fields you care about.
+ *
+ * @example
+ * // pretty-print large snapshots across multiple lines and truncate them
+ * setErrorFormatting({ enabled: true })
+ *
+ * @example
+ * // only bound the message size, without reflowing it onto multiple lines
+ * setErrorFormatting({ enabled: true, indent: 0 })
+ *
+ * @example
+ * // tweak the truncation limits
+ * setErrorFormatting({ enabled: true, maxArrayLength: 3, maxStringLength: 40 })
+ *
+ * @param options A partial set of {@link ErrorFormattingOptions} to apply.
+ */
+export declare function setErrorFormatting(options: Partial<ErrorFormattingOptions>): void;
+/**
+ * Returns a copy of the current error formatting options (see
+ * {@link setErrorFormatting}). Useful for temporarily overriding and then
+ * restoring the configuration.
+ *
+ * @returns The current {@link ErrorFormattingOptions}.
+ */
+export declare function getErrorFormatting(): ErrorFormattingOptions;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type IModelType, type IAnyModelType, type IDisposer, type IMSTMap, type IMapType, type IMSTArray, type IArrayType, type IType, type IAnyType, type ModelPrimitive, type ISimpleType, type IComplexType, type IAnyComplexType, type IReferenceType, type _CustomCSProcessor, type _CustomOrOther, type _CustomJoin, type _NotCustomized, typecheck, escapeJsonPath, unescapeJsonPath, joinJsonPath, splitJsonPath, type IJsonPatch, type IReversibleJsonPatch, decorate, addMiddleware, type IMiddlewareEvent, type IActionTrackingMiddleware2Call, type IMiddlewareHandler, type IMiddlewareEventType, type IActionTrackingMiddlewareHooks, type IActionTrackingMiddleware2Hooks, process, isStateTreeNode, type IStateTreeNode, type IAnyStateTreeNode, flow, castFlowReturn, applyAction, onAction, type IActionRecorder, type ISerializedActionCall, recordActions, createActionTrackingMiddleware, createActionTrackingMiddleware2, setLivelinessChecking, getLivelinessChecking, type LivelinessMode, setLivelynessChecking, // to be deprecated
+export { type IModelType, type IAnyModelType, type IDisposer, type IMSTMap, type IMapType, type IMSTArray, type IArrayType, type IType, type IAnyType, type ModelPrimitive, type ISimpleType, type IComplexType, type IAnyComplexType, type IReferenceType, type _CustomCSProcessor, type _CustomOrOther, type _CustomJoin, type _NotCustomized, typecheck, escapeJsonPath, unescapeJsonPath, joinJsonPath, splitJsonPath, type IJsonPatch, type IReversibleJsonPatch, decorate, addMiddleware, type IMiddlewareEvent, type IActionTrackingMiddleware2Call, type IMiddlewareHandler, type IMiddlewareEventType, type IActionTrackingMiddlewareHooks, type IActionTrackingMiddleware2Hooks, process, isStateTreeNode, type IStateTreeNode, type IAnyStateTreeNode, flow, castFlowReturn, applyAction, onAction, type IActionRecorder, type ISerializedActionCall, recordActions, createActionTrackingMiddleware, createActionTrackingMiddleware2, setLivelinessChecking, getLivelinessChecking, type LivelinessMode, setErrorFormatting, getErrorFormatting, type ErrorFormattingOptions, setLivelynessChecking, // to be deprecated
 type LivelynessMode, // to be deprecated
 type ModelSnapshotType, type ModelCreationType, type ModelSnapshotType2, type ModelCreationType2, type ModelInstanceType, type ModelInstanceTypeProps, type ModelPropertiesDeclarationToProperties, type ModelProperties, type ModelPropertiesDeclaration, type ModelActions, type ITypeUnion, type CustomTypeOptions, type UnionOptions, type Instance, type SnapshotIn, type SnapshotOut, type SnapshotOrInstance, type TypeOrStateTreeNodeToStateTreeNode, type UnionStringArray, getType, getChildType, onPatch, onSnapshot, applyPatch, type IPatchRecorder, recordPatches, protect, unprotect, isProtected, applySnapshot, getSnapshot, hasParent, getParent, hasParentOfType, getParentOfType, getRoot, getPath, getPathParts, isRoot, resolvePath, resolveIdentifier, getIdentifier, tryResolve, getRelativePath, clone, detach, destroy, isAlive, addDisposer, hasEnv, getEnv, walk, type IModelReflectionData, type IModelReflectionPropertiesData, type IMaybeIType, type IMaybe, type IMaybeNull, type IOptionalIType, type OptionalDefaultValueOrFunction, type ValidOptionalValue, type ValidOptionalValues, getMembers, getPropertyMembers, type TypeOfValue, cast, castToSnapshot, castToReferenceSnapshot, isType, isArrayType, isFrozenType, isIdentifierType, isLateType, isLiteralType, isMapType, isModelType, isOptionalType, isPrimitiveType, isReferenceType, isRefinementType, isUnionType, tryReference, isValidReference, type OnReferenceInvalidated, type OnReferenceInvalidatedEvent, type ReferenceOptions, type ReferenceOptionsGetSet, type ReferenceOptionsOnInvalidated, type ReferenceIdentifier, type ISnapshotProcessor, type ISnapshotProcessors, getNodeId, type IActionContext, getRunningActionContext, isActionContextChildOf, isActionContextThisOrChildOf, types, types as t, // We do this as a less ambiguous term for the traditional types module, which sometimes gets confused when discussing "types" in general
 toGeneratorFunction, toGenerator } from "./internal";

package/dist/internal.d.ts

@@ -10,6 +10,7 @@ export * from "./middlewares/createActionTrackingMiddleware2";
 export * from "./middlewares/on-action";
 export * from "./core/action";
 export * from "./core/actionContext";
+export * from "./core/type/errorFormatting";
 export * from "./core/type/type-checker";
 export * from "./core/node/identifier-cache";
 export * from "./core/node/create-node";

package/dist/mobx-state-tree.js

@@ -3539,30 +3539,207 @@ function isActionContextThisOrChildOf(actionContext, parentOrThis) {
     return _isActionContextThisOrChildOf(actionContext, parentOrThis, true);
 }
 
-function safeStringify(value) {
+var defaultOptions = {
+    enabled: false,
+    indent: 2,
+    maxStringLength: 100,
+    maxArrayLength: 10,
+    maxPropertyCount: 30,
+    maxDepth: 5
+};
+var currentOptions = __assign({}, defaultOptions);
+/**
+ * Configures how snapshots/values and type shapes are formatted inside
+ * type-checking error messages. This is **opt-in**: by default MST keeps its
+ * original single-line error formatting, so enabling this does not change
+ * behavior for anyone who doesn't call it.
+ *
+ * The given options are merged over the current ones, so you can set only the
+ * fields you care about.
+ *
+ * @example
+ * // pretty-print large snapshots across multiple lines and truncate them
+ * setErrorFormatting({ enabled: true })
+ *
+ * @example
+ * // only bound the message size, without reflowing it onto multiple lines
+ * setErrorFormatting({ enabled: true, indent: 0 })
+ *
+ * @example
+ * // tweak the truncation limits
+ * setErrorFormatting({ enabled: true, maxArrayLength: 3, maxStringLength: 40 })
+ *
+ * @param options A partial set of {@link ErrorFormattingOptions} to apply.
+ */
+function setErrorFormatting(options) {
+    currentOptions = __assign(__assign({}, currentOptions), options);
+}
+/**
+ * Returns a copy of the current error formatting options (see
+ * {@link setErrorFormatting}). Useful for temporarily overriding and then
+ * restoring the configuration.
+ *
+ * @returns The current {@link ErrorFormattingOptions}.
+ */
+function getErrorFormatting() {
+    return __assign({}, currentOptions);
+}
+
+function safeStringify(value, indent) {
     try {
-        return JSON.stringify(value);
+        return JSON.stringify(value, null, indent);
     }
     catch (e) {
         // istanbul ignore next
         return "<Unserializable: ".concat(e, ">");
     }
 }
+function shortenPrintValue(valueInString) {
+    return valueInString.length < 280
+        ? valueInString
+        : "".concat(valueInString.substring(0, 272), "......").concat(valueInString.substring(valueInString.length - 8));
+}
+/**
+ * Returns a clone of `value` in which overly long strings are clipped and large
+ * arrays/objects (or values nested too deeply) are summarized, so the result is
+ * safe to print in an error message without flooding the screen.
+ */
+function truncateForDisplay(value, depth, options) {
+    if (typeof value === "string") {
+        return value.length > options.maxStringLength
+            ? "".concat(value.slice(0, options.maxStringLength), "\u2026 (").concat(value.length - options.maxStringLength, " more characters)")
+            : value;
+    }
+    if (Array.isArray(value)) {
+        if (depth >= options.maxDepth)
+            return "[…]";
+        var items = value
+            .slice(0, options.maxArrayLength)
+            .map(function (item) { return truncateForDisplay(item, depth + 1, options); });
+        if (value.length > options.maxArrayLength) {
+            items.push("\u2026 ".concat(value.length - options.maxArrayLength, " more items"));
+        }
+        return items;
+    }
+    if (isPlainObject(value)) {
+        if (depth >= options.maxDepth)
+            return "{…}";
+        var result_1 = {};
+        var keys = Object.keys(value);
+        keys.slice(0, options.maxPropertyCount).forEach(function (key) {
+            result_1[key] = truncateForDisplay(value[key], depth + 1, options);
+        });
+        if (keys.length > options.maxPropertyCount) {
+            result_1["…"] = "".concat(keys.length - options.maxPropertyCount, " more keys");
+        }
+        return result_1;
+    }
+    return value;
+}
 /**
  * @internal
  * @hidden
  */
 function prettyPrintValue(value) {
-    return typeof value === "function"
-        ? "<function".concat(value.name ? " " + value.name : "", ">")
-        : isStateTreeNode(value)
-            ? "<".concat(value, ">")
-            : "`".concat(safeStringify(value), "`");
+    if (typeof value === "function") {
+        return "<function".concat(value.name ? " " + value.name : "", ">");
+    }
+    if (isStateTreeNode(value)) {
+        return "<".concat(value, ">");
+    }
+    var options = getErrorFormatting();
+    if (!options.enabled) {
+        // Default behavior: serialize the value compactly on a single line.
+        // JSON.stringify returns `undefined` for values like `undefined` itself,
+        // which the template literal coerces back to a string.
+        return "`".concat(safeStringify(value), "`");
+    }
+    // Opt-in behavior: clip long strings, big arrays/objects and deep nesting, and
+    // (when indent > 0) pretty-print the result across multiple lines.
+    var truncated = truncateForDisplay(value, 0, options);
+    return "`".concat(safeStringify(truncated, options.indent || undefined), "`");
 }
-function shortenPrintValue(valueInString) {
-    return valueInString.length < 280
-        ? valueInString
-        : "".concat(valueInString.substring(0, 272), "......").concat(valueInString.substring(valueInString.length - 8));
+/**
+ * Re-indents a type description (as produced by `IType.describe()`) across
+ * multiple lines, by breaking after the `{`, `}` and `;` separators used in
+ * model shapes (while leaving union `|` and array `[]` parts inline).
+ * Characters inside string literals (e.g. literal types like `"a;b"`) are left
+ * untouched.
+ *
+ * `indentSize` is the number of spaces per nesting level; when it is `0` (or
+ * negative) the description is returned unchanged on a single line. As this runs
+ * while formatting an error that is already being thrown, it must never throw
+ * itself: any unexpected input falls back to the original, unformatted
+ * description.
+ *
+ * @internal
+ * @hidden
+ */
+function prettyPrintDescription(description, indentSize) {
+    if (indentSize <= 0) {
+        return description;
+    }
+    try {
+        var step_1 = " ".repeat(indentSize);
+        var result_2 = "";
+        var depth_1 = 0;
+        var stringDelimiter = null;
+        var escaped = false;
+        var newline = function () {
+            // drop any trailing spaces (e.g. the "{ " / "; " separators) before breaking,
+            // and never let a malformed (over-closed) shape produce a negative indent
+            result_2 = result_2.replace(/[ \t]+$/, "");
+            result_2 += "\n" + step_1.repeat(Math.max(0, depth_1));
+        };
+        for (var i = 0; i < description.length; i++) {
+            var char = description[i];
+            if (stringDelimiter) {
+                result_2 += char;
+                if (escaped) {
+                    escaped = false;
+                }
+                else if (char === "\\") {
+                    escaped = true;
+                }
+                else if (char === stringDelimiter) {
+                    stringDelimiter = null;
+                }
+                continue;
+            }
+            switch (char) {
+                case '"':
+                case "'":
+                    stringDelimiter = char;
+                    result_2 += char;
+                    break;
+                case "{":
+                    depth_1++;
+                    result_2 += "{";
+                    newline();
+                    while (description[i + 1] === " ")
+                        i++;
+                    break;
+                case "}":
+                    depth_1--;
+                    newline();
+                    result_2 += "}";
+                    break;
+                case ";":
+                    result_2 += ";";
+                    newline();
+                    while (description[i + 1] === " ")
+                        i++;
+                    break;
+                default:
+                    result_2 += char;
+            }
+        }
+        return result_2;
+    }
+    catch (e) {
+        // istanbul ignore next - defensive: never let formatting hide the real error
+        return description;
+    }
 }
 function toErrorString(error) {
     var value = error.value;
@@ -3581,12 +3758,18 @@ function toErrorString(error) {
             ? "value"
             : "snapshot";
     var isSnapshotCompatible = type && isStateTreeNode(value) && type.is(getStateTreeNode(value).snapshot);
+    // When error formatting is enabled, the type shape is re-indented using the
+    // same indent setting as values; otherwise it's left on a single line.
+    var formatting = getErrorFormatting();
+    var describeType = function (t) {
+        return formatting.enabled ? prettyPrintDescription(t.describe(), formatting.indent) : t.describe();
+    };
     return ("".concat(pathPrefix).concat(currentTypename, " ").concat(prettyPrintValue(value), " is not assignable ").concat(type ? "to type: `".concat(type.name, "`") : "") +
         (error.message ? " (".concat(error.message, ")") : "") +
         (type
             ? isPrimitiveType(type) || isPrimitive(value)
                 ? "."
-                : ", expected an instance of `".concat(type.name, "` or a snapshot like `").concat(type.describe(), "` instead.") +
+                : ", expected an instance of `".concat(type.name, "` or a snapshot like `").concat(describeType(type), "` instead.") +
                     (isSnapshotCompatible
                         ? " (Note that a snapshot of the provided value is compatible with the targeted type)"
                         : "")
@@ -3649,7 +3832,14 @@ function validationErrorsToString(type, value, errors) {
     if (errors.length === 0) {
         return undefined;
     }
-    return ("Error while converting ".concat(shortenPrintValue(prettyPrintValue(value)), " to `").concat(type.name, "`:\n\n    ") + errors.map(toErrorString).join("\n    "));
+    // When formatting is disabled, keep the original behavior of capping the
+    // header value's length; when enabled, truncation already bounds its size.
+    var printedValue = prettyPrintValue(value);
+    var headerValue = getErrorFormatting().enabled
+        ? printedValue
+        : shortenPrintValue(printedValue);
+    return ("Error while converting ".concat(headerValue, " to `").concat(type.name, "`:\n\n    ") +
+        errors.map(toErrorString).join("\n    "));
 }
 
 var identifierCacheId = 0;
@@ -9030,6 +9220,7 @@ exports.escapeJsonPath = escapeJsonPath;
 exports.flow = flow;
 exports.getChildType = getChildType;
 exports.getEnv = getEnv;
+exports.getErrorFormatting = getErrorFormatting;
 exports.getIdentifier = getIdentifier;
 exports.getLivelinessChecking = getLivelinessChecking;
 exports.getMembers = getMembers;
@@ -9077,6 +9268,7 @@ exports.recordActions = recordActions;
 exports.recordPatches = recordPatches;
 exports.resolveIdentifier = resolveIdentifier;
 exports.resolvePath = resolvePath;
+exports.setErrorFormatting = setErrorFormatting;
 exports.setLivelinessChecking = setLivelinessChecking;
 exports.setLivelynessChecking = setLivelynessChecking;
 exports.splitJsonPath = splitJsonPath;