Representing arbitrary JSON values.

[maxgurewitz]

Hello, I'm trying to represent the following type,

export type JSONValue =
  | string
  | number
  | null
  | boolean
  | { [x: string]: JSONValue }
  | JSONValue[];

Which is intended to represent an arbitrary JSON value.

However, typebox seems to be missing support for index signatures for { [x: string]: JSONValue }. I can't use Record's instead,

export const JSONValue = Type.Recursive((Node) =>
  Type.Union([
    Type.Null(),
    Type.String(),
    Type.Number(),
    Type.Boolean(),
    Type.Record(Type.String(), Node),
    Type.Array(Node),
  ])
);

export type JSONValue = Static<typeof JSONValue>;

because I get the error Type instantiation is excessively deep and possibly infinite.

Any tips? Thank you!

[sinclairzx81]

@maxgurewitz Hi,

I would recommend using Type.Unknown() or Type.Any() types over explicitly trying to define every possible type expressible in JSON (of which there could be near infinite possible types). TypeScript offers unknown and any types for this reason, and where the unknown type is an alias for "universal type". Also note that this type cannot be expressed in TypeScript which I believe is due to the Record<string, JSONValue> type resolving to a empty set for all possible variants of itself (so it's cyclic and non-resolvable)

TypeScript Link Here

export type JSONValue = null | string | number | boolean | Record<string, JSONValue> | Array<JSONValue>
//          ^ Type alias 'JSONValue' circularly references itself.

In practice though, both the JSONValue (as you've defined) and unknown types would require recipients of values matching these types to explicitly narrow down to the specific type before use. Consider the following...

function receive(value: Static<typeof JSONValue>) {
  // note: explicit narrowing of value is required before use
  if(typeof value === 'string') console.log(value.toLowerCase())
  if(typeof value === 'number') console.log(value.toFixed(2))
  // and so on
}

But this is true for unknown also.

const JSONValue = Type.Unknown()

function receive(value: Static<typeof JSONValue>) {
  // note: explicit narrowing of value is required before use
  if(typeof value === 'string') console.log(value.toLowerCase())
  if(typeof value === 'number') console.log(value.toFixed(2))
  // and so on
}

So, from this, using Type.Unknown() is generally the way to go for expressing all possible values.
Hope this helps
S

[maxgurewitz]

Hello. Thanks for the response! I was hoping for the type to exclude non-json-serializable types e.g Map, Date, undefined etc. which

export type JSONValue =
  | string
  | number
  | null
  | boolean
  | { [x: string]: JSONValue }
  | JSONValue[];

does. Does Type.Unknown() exclude these types?

[sinclairzx81]

I was hoping for the type to exclude non-json-serializable types e.g Map, Date, undefined ..... Does Type.Unknown() exclude these types?

The unknown type is a universal type, so would also include Map, Set, Date and undefined. This generally isn't going to cause a problem as received JSON values will never contain these kinds of values. However, if wanting type protection before encoding values (to ensure the value being encoded doesn't contain these types), you can write a custom type for that. The following implements JSONValue by way of a custom type.

import { TypeCompiler } from '@sinclair/typebox/compiler'
import { TypeSystem } from '@sinclair/typebox/system'

// ----------------------------------------------------------------
// JSONValue: Custom Type
// ----------------------------------------------------------------
function JSONValueCheck(value: unknown): boolean {
  if(value === undefined) return false
  if(value instanceof Map) return false
  if(value instanceof Set) return false
  if(value instanceof Date) return false
  // todo: add more disallowed types here
  if(typeof value === 'object' && value !== null && !Array.isArray(value)) return Object.values(value).every(prop => JSONValueCheck(prop))
  if(Array.isArray(value)) return value.every(element => JSONValueCheck(element))
  return true
}
const JSONValue = TypeSystem.CreateType<unknown>('JSONValue', (_, value) => JSONValueCheck(value))
//                                     ^ Custom type infers as unknown

// ----------------------------------------------------------------
// Example
// ----------------------------------------------------------------

const T = JSONValue() // Use JSONValue like any other type

const C = TypeCompiler.Compile(T)

// allowed
C.Check(1)                   // true
C.Check(true)                // true
C.Check('hello')             // true
C.Check(null)                // true
C.Check({})                  // true
C.Check([])                  // true

// disallowed
C.Check(new Map())           // false
C.Check([new Map()])         // false
C.Check({ map: new Map() })  // false

Note, custom types only work for TypeBox's TypeCompiler and Value modules, so cannot be used with Ajv. Also note that the inference type for JSONValue is still unknown as there is no way to express disallowed types in the TypeScript type system (which extends to TypeBox also). To do better than unknown, TypeScript needs negated (disallowed) types, see link below for a TS issue for negated types (which discuss them specifically in the context of JSON serialization)

microsoft/TypeScript#4196

Hope this helps

[maxgurewitz]

Great. Thank you so much! Great explanation of how to create custom types in typebox for this use case.