README.md 4.8 KB
description: "Lossless JSON validation, detached snapshots, deep freezing, structural equality, and exhaustive-union helpers for runtime packages."
kind: "package-library"
@deepseek-ai/dsh-util-values
English | 中文
Summary
dsh-util-values gives runtime packages one implementation for lossless JSON values, immutable object graphs, structural JSON equality, and exhaustive closed-union failures. Callers can validate untrusted values, detach a JSON snapshot, freeze a published value, compare JSON-compatible data, or terminate an unreachable branch without importing a capability package. The helpers hold no shared registry, constructor identity, or mutable module state.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Known Limitations and Deferred Work
- Dev Note
Use this package
Validate or snapshot JSON data
Use isJsonValue() for a predicate and snapshotJsonValue() when the caller also needs a detached copy. Both accept only lossless JSON roots: null, booleans, finite numbers other than negative zero, strings, dense intrinsic arrays, and plain or null-prototype records with enumerable string keys. Cycles, sparse arrays, symbol or non-enumerable own properties, functions, and class instances are rejected.
import { isJsonValue, snapshotJsonValue, type JsonValue } from '@deepseek-ai/dsh-util-values'
declare const input: unknown
if (!isJsonValue(input)) throw new TypeError('expected lossless JSON')
const snapshot = snapshotJsonValue(input) as JsonValue
Publish, compare, or retain keyed values
deepFreeze(value) freezes an object graph in place and returns the same value. It walks enumerable string-keyed children and deliberately leaves live AbortSignal objects mutable. deepEqualJson(a, b) compares JSON-compatible arrays and records structurally; callers must validate hostile or unconstrained values before comparison.
WeakMapWithValues<Key, Value> combines weak object-key lookup with a strongly retained, insertion-ordered values set. Each value belongs to one key. The owner must call delete(key) or clear() at the corresponding lifecycle boundary; the collection does not perform automatic cleanup.
Close a discriminated union
Use assertNever(value, context?) in the default branch of a closed discriminated union. A newly added variant then fails TypeScript compilation at every exhaustive switch, while a runtime value that escaped its declared type throws with the optional context label.
Understand the implementation
Implementation internals — click to expand
The JSON validator uses an explicit work stack and tracks only the active ancestor chain, so deeply nested values do not consume the JavaScript call stack and repeated non-cyclic references remain valid. Snapshot writes use own data properties, including for names such as `__proto__`. Value operations derive their result only from their arguments; `WeakMapWithValues` stores only instance-owned associations. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | JSON value type, validation and snapshot traversal, structural equality, deep freezing, weak-key/strong-value associations, and exhaustive-union failure | | — | No runtime invariant companion is published because these value operations have no shared runtime state; unit tests cover their algebra. |Further Exploration
- Utility package map — adjacent stateless helpers.
- Session subsystem — durable events that require lossless JSON.
- Tools subsystem — schema validation and canonical tool results built on
JsonValue.
Known Limitations and Deferred Work
deepEqualJsonassumes JSON-compatible inputs — it is not a general object comparator and does not define semantics for prototypes, symbols, accessors, cycles, maps, or sets.deepFreezefollows enumerable string-keyed children — it does not turn arbitrary host objects into immutable data, and it intentionally skips liveAbortSignalinstances.WeakMapWithValuesrequires explicit cleanup and unique values — values remain strongly held until their owning key is deleted or the collection is cleared, and one value must not be shared by several keys.