or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdindex.mdjson-conversion.mdtransport.md
tile.json

index.mddocs/

@deck.gl/json

@deck.gl/json provides a JSON configuration system for deck.gl that enables declarative specification of visualization layers and their properties through JSON format. It converts textual JSON specifications into JavaScript objects and functions, allowing backend systems to generate dynamic visualizations without requiring frontend JavaScript modifications.

Package Information

  • Package Name: @deck.gl/json
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @deck.gl/json

Core Imports

import { JSONConverter, JSONConfiguration, Transport } from "@deck.gl/json";

CommonJS:

const { JSONConverter, JSONConfiguration, Transport } = require("@deck.gl/json");

Utility functions (for advanced use):

import { 
  _convertFunctions, 
  _parseExpressionString, 
  _shallowEqualObjects 
} from "@deck.gl/json";

Basic Usage

import { JSONConverter, JSONConfiguration } from "@deck.gl/json";

// Create a configuration with your deck.gl classes and enums
const configuration = new JSONConfiguration({
  classes: {
    ScatterplotLayer: ScatterplotLayer, // Your deck.gl layer classes
    MapView: MapView
  },
  enumerations: {
    COORDINATE_SYSTEM: COORDINATE_SYSTEM
  }
});

// Create converter
const converter = new JSONConverter({ configuration });

// Convert JSON to deck.gl props
const jsonData = {
  "layers": [
    {
      "@@type": "ScatterplotLayer",
      "id": "scatter-layer",
      "data": [
        {"position": [0, 0], "radius": 10}
      ],
      "coordinateSystem": "@@#COORDINATE_SYSTEM.DEFAULT"
    }
  ]
};

const deckProps = converter.convert(jsonData);
// Returns: { layers: [ScatterplotLayerInstance] }

Architecture

@deck.gl/json is built around several key components:

  • JSONConverter: Main converter class that processes JSON configurations into deck.gl props
  • JSONConfiguration: Configuration manager that defines available classes, functions, constants, and enums
  • Transport System: Infrastructure for back-channel messaging between JSON layer instances and host applications
  • Expression Parser: Safe evaluation engine for converting string expressions to JavaScript functions
  • Syntactic Sugar: Special identifiers for referencing functions (@@=), constants (@@#), types (@@type), and functions (@@function)

Capabilities

JSON Conversion

Core functionality for converting JSON configurations into deck.gl layer props with class instantiation, function parsing, and constant resolution.

class JSONConverter {
  constructor(props: JSONConverterProps);
  convert(json: any): any;
  setProps(props: JSONConverterProps): void;
  mergeConfiguration(config: any): void;
  finalize(): void;
}

interface JSONConverterProps {
  configuration: JSONConfiguration | Record<string, any>;
  onJSONChange?: Function;
}

JSON Conversion

Configuration Management

Configuration system for managing available classes, functions, constants, and conversion settings.

class JSONConfiguration {
  constructor(...configurations: any[]);
  merge(configuration: any): void;
  validate(configuration: any): boolean;
}

Configuration Management

Transport System

Back-channel messaging infrastructure for communication between JSON layer instances and host applications.

class Transport {
  constructor(name?: string);
  static setCallbacks(callbacks: TransportCallbacks): void;
  getRootDOMElement(): HTMLElement | null;
  sendJSONMessage(): void;
  sendBinaryMessage(): void;
  static _stringifyJSONSafe(value: any): string;
}

interface TransportCallbacks {
  onInitialize?: (message: any) => void;
  onFinalize?: (message: any) => void;
  onMessage?: (message: any) => void;
}

Transport System

Utility Functions

The package also exports several utility functions for internal use:

/**
 * Converts function-valued props from strings to actual functions
 * @param props - Object containing properties to convert
 * @param configuration - JSON configuration for function parsing
 * @returns New object with converted function properties
 */
function _convertFunctions(props: any, configuration: JSONConfiguration): any;

/**
 * Parses expression strings into JavaScript functions with security protection
 * @param propValue - Expression string to parse (e.g., "d => d.radius * 2")
 * @param configuration - JSON configuration for parsing context
 * @returns Compiled function that evaluates the expression
 */
function _parseExpressionString(propValue: string, configuration: JSONConfiguration): Function;

/**
 * Performs shallow equality comparison between two objects
 * @param a - First object to compare
 * @param b - Second object to compare
 * @returns True if objects are shallow equal
 */
function _shallowEqualObjects(a: any, b: any): boolean;

Syntactic Sugar Constants

The package defines special identifiers used in JSON for referencing functions, constants, types, and function objects:

/** Identifier prefix for function expressions: "@@=" */
const FUNCTION_IDENTIFIER = "@@=";

/** Identifier prefix for constants and enums: "@@#" */
const CONSTANT_IDENTIFIER = "@@#";

/** JSON key for specifying class types: "@@type" */  
const TYPE_KEY = "@@type";

/** JSON key for specifying function objects: "@@function" */
const FUNCTION_KEY = "@@function";

Types

// Core configuration properties
interface JSONConverterProps {
  configuration: JSONConfiguration | Record<string, any>;
  onJSONChange?: Function;
}

interface TransportCallbacks {
  onInitialize?: (message: any) => void;
  onFinalize?: (message: any) => void;
  onMessage?: (message: any) => void;
}