Discovery.js

Discovery.js is a framework designed for ad hoc JSON data analysis, creating shareable server-less reports, and building dashboards. It provides tools to discover patterns and insights within JSON documents.

Beyond the core framework, Discovery.js powers several specialized tools:

• JsonDiscovery: A browser extension (Chrome, Edge, Firefox) that acts as an advanced JSON viewer, allowing users to discover JSON documents and generate reports directly in the browser.
• Statoscope: A toolkit for analyzing and validating webpack bundles.
• CPUpro: A tool for rethinking CPU profile analysis.
• react-native-bundle-discovery: A toolkit for analyzing and visualizing Metro bundles.

Encodings are configurations used during payload loading to transform raw data into JavaScript objects. Discovery.js uses encodings to determine how to interpret incoming data chunks or full payloads.

When loading data, Discovery.js checks the test function of each configured encoding against the first chunk of the payload. If test returns true, that encoding is used to decode the data.

Custom encodings are applied before the default encodings. The default application order is:

1. jsonxl (snapshot9), non-streaming
2. json (utilizing @discoveryjs/json-ext), streaming

The Discovery.js ecosystem includes several companion projects for different workflows:

• Discovery CLI: Command-line tools used to serve and build projects based on Discovery.js.
• Jora: A dedicated data query language designed for working with JSON.
• Jora CLI: A command-line interface tool to process JSON data using the Jora query language.

You can register custom encodings by passing an encodings array to the configuration object of an App, Widget, or Model.

Additionally, preloaders can pass encodings to a data loader via the loadDataOptions object. The Model (the base class for App and Widget) integrates these encodings into its loadData* method calls.

new App({
    encodings: [
        {
            name: 'lines/counter',
            test: () => true, // Always applicable
            streaming: false,
            decode: (payload) => new TextDecoder().decode(payload).split('\n').length
        }
    ]
});

For an application to communicate with a host via the Embed API, it must explicitly enable the embed feature. This can be done when instantiating an App or a ViewModel.

Using App:

const myapp = new App({ embed: true });

Using ViewModel:

import { ViewModel, embed } from '@discoveryjs/discovery';

const myapp = new ViewModel({
    extensions: [
        embed
    ]
});

import { App, ViewModel, embed } from '@discoveryjs/discovery';

// App
const myapp = new App({ embed: true });

// ViewModel
const myapp = new ViewModel({
    extensions: [
        embed
    ]
});

You can enable data uploading capabilities in either an App or a Widget instance. This feature allows users to load and unload data using file inputs or drag-and-drop functionality.

To enable it with default settings in an App:

const myapp = new App({ upload: true });

To enable it in a Widget using the extensions option:

const myapp = new Widget({
    extensions: [
        upload
    ]
});

import { App, Widget, upload } from '@discoveryjs/discovery';

// App
const myapp = new App({ upload: true });

// Widget
const myapp = new Widget({
    extensions: [
        upload
    ]
});

To ensure the embedded app's routing stays in sync with the host page's location, follow this recommended sequence of API calls within the connectToEmbedApp callback:

1. Call embedApp.setRouterPreventLocationUpdate(true) to prevent immediate feedback loops.
2. Call embedApp.setPageHash(location.hash) to sync the hash.
3. Call embedApp.setLocationSync(true) to enable ongoing synchronization.

import { connectToEmbedApp } from "@discoveryjs/discovery/dist/discovery-embed.js";
    
const disconnect = connectToEmbedApp(iframe, (embedApp) => {
    // ... any other setup

    // recommended order of API calls to sync location state with embed app
    embedApp.setRouterPreventLocationUpdate(true);
    embedApp.setPageHash(location.hash);
    embedApp.setLocationSync(true);
});

Extensions allow you to apply logic to a Model instance. An extension can be a single function, an array of functions, or an object containing multiple extension functions. You apply them using model.apply(extensions). This is useful for modularizing features like custom text view renderers or shared query logic across multiple models.

const myExtension = (host: Model) => {
    host.on('data', () => console.log('Data updated!'));
};

model.apply(myExtension);

// Or applying an array of extensions
model.apply([ext1, ext2]);

When loading data, the process is tracked via a LoadDataState object. This state allows you to monitor the lifecycle of a data request and its progress. The stage indicates the current phase of the operation:

• inited: Initialized
• request: Requesting the resource
• receiving: Receiving data chunks
• decoding: Decoding the received payload
• received: Data loading and decoding complete
• error: An error occurred during the process

If the stage is not error, you can monitor LoadDataStateProgress to track completion:

• done: Boolean indicating if the process is finished.
• completed: The amount of data processed.
• total: The total amount of data expected (if known).
• elapsed: Time elapsed during the operation.
• units: Typically 'bytes'.