npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@holistics/anfra-sdk

v0.21.0

Published

Data Apps on anfra: the authoring layer (app), what hosts one (host), anfra's plugins (plugins), the core API client (api), and their shared contract (common)

Readme

@holistics/anfra-sdk

The TypeScript SDK for Data Apps: interactive analyses over a repo's datasets, each defined by a single HTML file (a Data App definition) that declares queries in AQL, with controls and cross-filters, and renders the results with its own HTML, CSS and JS. The SDK supplies data and state, never UI.

It started as a fork of the Holistics Data App SDK, and diverges from it.

npm install @holistics/anfra-sdk

Each anfra release publishes it at its own version: the SDK's API client matches that release's core API.

Entrypoints

The package root exports nothing; each entrypoint is for a different side of a Data App.

| Entrypoint | For | Holds | |---|---|---| | @holistics/anfra-sdk/app | a Data App definition, in its frame | the app runtime (createApp, queries, controls, cross-filters, results and state), and the frame bootstrap that provisions it from its host | | @holistics/anfra-sdk/host | the page hosting a Data App | the host runtime: the plugins and middleware a page installs, provisioning each frame, mounting it sandboxed, and answering its calls over the bridge; definePlugin for a plugin of your own | | @holistics/anfra-sdk/plugins | the page hosting a Data App | anfra's own plugins: core (queries), export, lineage, render, inspect | | @holistics/anfra-sdk/build | a plugin's build, in Node | buildFrameHalf: a plugin's frame half as the script a host provisions | | @holistics/anfra-sdk/testing | a plugin's tests | testFrame: a frame half run on the real kernel against a stand-in host | | @holistics/anfra-sdk/api | the host's page, scripts, tests | a client for the core API, generated from anfra's spec, and a Backend over it | | @holistics/anfra-sdk/common | all of the above | the contract they share: types, error classes, the bridge's messages |

Writing a Data App

A definition needs no setup and imports nothing: its host provisions the SDK as the Anfra global before the definition's first script runs.

const app = Anfra.createApp({ title: 'Sales' });

const status = app.createFilter('status', { dataset: 'ecommerce', field: 'orders.status' });
const byRegion = app.createQuery('byRegion', {
  dataset: 'ecommerce',
  aql: 'explore { dimensions { region: users.region } measures { revenue: sum(orders.amount) } }',
});
app.mapControl(status, byRegion, { field: 'orders.status' });

app.subscribe(() => render(byRegion.result));
await app.execute();

An app may change what it declared while it runs, as a chart or dashboard builder does: update a query or a control in place (byRegion.update({ aql })), remove() one with its edges, or remove() one edge (mapControl and mapCrossFilter return it). A name is an entity's identity and never changes. Changes run at the next app.execute(), so several go out as one run.

Everything beyond queries comes from a plugin the host installed, which adds its API under its own name (query.export, Anfra.render, Anfra.lineage). Where the host didn't install it, the member isn't there: check Anfra.plugins.has(name) before using an optional one.

Data Apps written before plugins read Anfra.features.export (.render, .lineage). It still answers, from the installed plugins, but it is deprecated and warns in the console: replace it with Anfra.plugins.has('export'). It goes in the next breaking release.

A reader can download a query's whole result, with the inputs its result on screen was run with (the export plugin):

if (Anfra.plugins.has('export') && Anfra.user.permissions.canExportData) {
  button.onclick = () => byRegion.export().catch((err) => showError(err.message));
}

export() resolves once the file is made and the host has started saving it, with its link and rowCount. The file is a CSV named after the app and the query unless you pass filename.

A reader can download a picture of the app, or of one block or container, as they see it (the render plugin):

await Anfra.render({ block: 'trend', format: 'png' });   // or 'pdf'; no node: the whole app

It works only where the host installed render (anfra serve does). Check Anfra.plugins.has('render') and Anfra.user.permissions.canExportData before offering it, and mark what shouldn't be drawn (the download button itself) data-anfra-render="skip". Serve images and web fonts with CORS: an image without it is left blank (listed in the result's omitted), a font without it falls back.

Anfra.datasets describes what there is to query. For TypeScript, @holistics/anfra-sdk/ambient declares the global. A plugin's members are typed as optional: check the member itself (if (Anfra.render), query.export?.()), which narrows it.

Anfra.lineage({ parent: 'orders', child: 'amount' }) (the lineage plugin) traces fields through the repo's catalog, each named by its parent and its name in it: what each is built from, as a diagram to draw (results[i].diagram), or why it could not be (results[i].error). It reads the catalog the host last ingested (anfra ingest).

A definition can mark its parts, so a host's inspect panel can show them as a tree and find them on the page:

<section data-anfra-container="page" data-anfra-label="Overview">
  <div data-anfra-block="revenue" data-anfra-query="byRegion">…</div>   <!-- a block drawn by a query -->
  <div data-anfra-block="trend">
    <div data-anfra-query="trend"></div>                                  <!-- the query's chart -->
    <select data-anfra-control="grain"></select>                          <!-- and its control -->
  </div>
</section>

A container holds anything; a block holds no container or block. data-anfra-query and data-anfra-control name what an element is drawn by (name, or app/name for a frame with several apps). Ids are unique per kind. The markup is optional and partial, read only while a host inspects, and never thrown over: a wrong name or a block inside a block is reported in the tree. byRegion.locate() scrolls to the elements marked with that query and shows them for a moment.

Hosting a Data App

import { coreApiBackend, coreClient, loadDatasets } from '@holistics/anfra-sdk/api';
import { createHost } from '@holistics/anfra-sdk/host';
import {
  corePlugin, exportPlugin, inspectPlugin, lineagePlugin, renderPlugin, viewUnderlyingDataPlugin,
} from '@holistics/anfra-sdk/plugins';

const client = coreClient('/api');                       // the core API, on whichever server serves it
const { datasets } = await loadDatasets(client);         // every dataset, through core.show
const backend = coreApiBackend(client, { datasets });    // queries, suggestions, exports and lineage, as core ops

const host = createHost({                                // one per page
  plugins: [
    corePlugin(backend),                                 // required: runs the queries
    exportPlugin(backend),                               // query.export()
    lineagePlugin(backend),                              // Anfra.lineage(), and the panel's Lineage tab
    renderPlugin(),                                      // Anfra.render(): the host saves PNGs and PDFs the frame makes
    inspectPlugin(),                                     // what an inspect panel needs
    viewUnderlyingDataPlugin(),                          // "View underlying data" on a chart point's menu
  ],
  allowOrigins: ['https://cdn.acme.com'],                // optional: more origins apps may load from
});

const mounted = host.mount({
  container: document.querySelector('#data-app')!,
  definition: await (await fetch('/appserve/files/sales/overview.html')).text(),
  datasets,
  user,
});
await mounted.call('render.draw', { format: 'pdf' });    // save a picture of the app
mounted.on('inspect.snapshot', ({ apps, structure }) => …);
await mounted.call('inspect.watch', true);               // start the snapshots
mounted.unmount();                                       // when done

A frame runs under a content policy the host puts first in its document: scripts, styles and fonts only from jsDelivr, cdnjs and Google Fonts and the host's allowOrigins, images from any https:// server, and no network beyond those origins: data reaches the app over the bridge only. A definition is one self-contained file; nothing beside it is served. See contentPolicy and docs/designs/security.md.

host.mount puts the definition in an iframe with sandbox="allow-scripts", as its srcdoc, with the frame's kernel, the provisioned data and each plugin's frame setup ahead of it. Every call the frame makes, and every call a plugin makes of another, goes through the host's one pipeline to the plugin that answers it. An export's file is saved from the host's page, by following its link: the frame can't download.

Middleware

Middleware wraps calls by name (*, core.*, core.submitQuery), in order of stage, then name:

createHost({
  plugins,
  middleware: [{
    name: 'log',
    match: '*',
    handle: async (request, call, next) => {
      const started = Date.now();
      try { return await next(request); } finally { console.log(call.name, call.caller, Date.now() - started); }
    },
  }],
});

It may change the request, answer in the plugin's place (not calling next), refuse (throwing), or change the answer. call.caller says who made the call: the frame, the host, or another plugin; call.origin who started it, through any plugins between (call.chain). Count what the frame started by origin: a query a plugin runs for the frame's request has the plugin as its caller. A handler forwarding a call or request the frame chose makes it with { asOrigin: true }, so it is refused if the frame couldn't make it itself.

A plugin of your own

A plugin adds a feature to the Data Apps on your host, such as a call from the frame to your server. Make one with definePlugin, build its frame half with @holistics/anfra-sdk/build, and test it with @holistics/anfra-sdk/testing. The guide, with a worked example, is docs/usage/sdk-plugins.md; the design is docs/designs/sdk-plugins.md.

The boundary

A Data App definition can come from any author, often an agent, which may not think of security while building an analysis. So the SDK guards it for its author, and makes the safe way the easy one:

  • Its frame has an opaque origin. Its own requests to the API are cross-origin, which anfra serve refuses, and carry no credentials on a platform that has them.
  • The frame reaches only the calls its host's plugins let it make (frame: true); every other call is the host's. Nothing else of the API is reachable from a frame.
  • @holistics/anfra-sdk/app imports only common: the script injected into a frame carries no API client. A test on the built frame script holds this.

Development

From the repository root, after pnpm install:

pnpm build:sdk     # dist/{common,app,host,plugins,api,build,testing}.js, with the frame script built into host and the plugins' into plugins
pnpm dev:sdk       # the same, rebuilt on change
pnpm test:sdk      # vitest

In web/sdk/, pnpm typecheck, and pnpm generate to regenerate src/api/schema.d.ts after the core API's spec (api/openapi.yaml) changes.