@discoveryjs/discovery

Discovery

Hackable JSON discovery tool

Documentation in progress...

Articles

• Discovery.js tutorials: quick start
• JsonDiscovery: Changing a way we’re viewing JSON in a browser

Examples of usage

• Statoscope – a toolkit to analyze and validate webpack bundle
• CPUpro – rethinking of CPU profile analysis
• CSS syntax reference (source)
• CSSWG spec drafts index (source)

Related projects

• Discovery CLI – CLI tools to serve & build projects based on Discovery.js
• JsonDiscovery – Chrome/Firefox browser extension built on Discovery which allows to discover a JSON document and make reports
• Jora – data query language
• Jora CLI – a tool to process JSON data using Jora in command line interface

Plugins

• @discoveryjs/view-plugin-highcharts – Highcharts plugin

Install

> npm install @discoveryjs/discovery

Base concepts

Model goes through data->prepare->render chain. Data can be modified with prepare function and rendered by various views and its combinations.

View is a function(el, config, data, context) where:

• el - DOM-element in which view will be rendered
• config - configuration of view
• data - data to render
• context - contains of model data, metaifo (createdAt, etc), router (optional), any user defined or view defined additional data

Page is a root view function(el, data, context). Similar to view it has all of its arguments except config.

Page

To define a page you should call discovery.page.define(pageId, render(el, data, context), options) where:

• pageId - unique page identifier
• render - page render function described above
• options - object with options:
  • reuseEl - do not clear container before render page (skiped for first render or pageId change)
  • init - invokes on first page render or pageId change
  • keepScrollOffset - dont scroll to page top if pageId didn't changed since last page render
  • encodeParams
  • decodeParams

Other handy methods for working with page:

• discovery.renderPage()
• discovery.setPage(pageId, pageRef, renderParam), discovery.setPageParams(renderParams) triggers renderPage()
• discovery.getPageContext() gets context of page

Special pages

There are some built-in special pages:

• default
• report
• not-found

You can override this pages with page.define() method

View

To define new view just call discovery.view.define(viewId, render, options) where:

• viewId - unique view identifier
• render - function(el, config, data, context) or view definition object
• options - object with following fields:
  • tag - a tag name for a view container element. When value is false or null then DocumentFragment is used as a container

You can render your view with discovery.view.render(el, view, data, context) where:

• view can be string viewId, ViewDefinition or Array<ViewDefinition> viewId will expand to { view: viewId }.

Also you can specify view as viewId:query, that will give you handy shortcut to { view: viewId, data: query }

• viewDefinition object with view definition settings:
  • view: string viewId
  • when: query, will be coerced to Boolean (but empty arrays and objects will coerce to false)
  • data: query (will be described later)
  • Also there can be view specific additional fields

Special views

Also special built-in sidebar view is available you can override this view with view.define

Queries

As a query you can specify string which will be processed by Jora so your data will be a result of following flow:

jora(value) -> function(data, context) -> data

Or you can use function(data, context) as query as well. Also you can use any data as query right away.

License

MIT

Changelog

1.0.0-beta.90 (15-11-2024)

• Added @discoveryjs/discovery/embed export
• Changed applyContainerStyles() to take a single darkmode value instead of "options", with supported values: true, false, 'true', 'false', 'dark', 'light' and 'auto'
• Changed applyContainerStyles() to avoid applying transition styles to the container, preventing unwanted flashes of opposite colors
• Changed source view to take source, syntax, lineNum, refs and maxSourceSizeToHighlight options. It attempts to derive these values from data when options are not explicitly provided for backward compatibility. The source can be derived from data as content (for backward compatibility) or source property
• Removed mime, binary and size data options for source view
• Bumped marked to ^14.1.4 (used in markdown view)
• Added styles for <kbd> in markdown view
• Improved string rendering in the values popup of signature view
• Fixed optional values statistics in signature view
• Fixed navigation history update on the query graph changes on discovery page
• Fixed scrollbar color schema in darkmode mode