Visualize.Chart.Builder.Bundle (Visualize v0.4.0)

Copy Markdown View Source

A collection of entries that can cross from one store into another (spec/14 §19.7).

Export takes the closure. Exporting an entry exports every entry it refers to, transitively, with their ids, so an import cannot dangle by construction. The bundle carries provenance — which store it came from, when, and the schema version it was exported at (spec/14 §9.1) — and each entry keeps its original id, so a repeated import of the same collection is detectable rather than a second copy of everything.

Importing one is the store's import/2 callback: a relocation through one old => new table, committed whole or not at all (D-103).

A bundle may carry a board (spec/15 §11, D-147): export_board/3 adds the board's map form, the closure of every component its cells reference and every stored theme it or its components name; import_board/3 checks all of it before any entry is put, then imports the entries through the store's own import/2 and rewrites the board's cell refs through the same table. A bundle carries no binding: bindings are the host's.

This module compiles only when Phoenix.Component is loaded (spec/10 §1.1, D-45, D-85).

Summary

Types

imported()

What a board's import gives: the board re-keyed, the id table, and the masks.

provenance()

Where a bundle came from, when, and the schema version it was exported at, which an importer older than it refuses (spec/14 §9.1).

t()

A bundle: its provenance, its entries in dependency order, and — for one export_board/3 made — the board in its map form (spec/15 §2.1), else nil.

Functions

export(store, ids, source)

The closure of an id through a store: the entry, and every entry it refers to, transitively, each once, in dependency order — an entry after everything it refers to.

export_board(store, board, source)

A board as a bundle (spec/15 §11.1): the board's map form, the closure of every component its cells reference, and the closure of every stored theme the board or its components name, dependencies first, with provenance as export/3 gives it.

import_board(store, bundle)

As import_board/3 with [] options.

import_board(store, bundle, opts)

A board bundle into a store (spec/15 §11.2): {:ok, %{board: board, ids: table, outside: ids}}, the board with every cell's ref rewritten to its component's new id, or {:error, errors}, every fault in the board's path shape.

Types

imported()

@type imported() :: %{
  board: Visualize.Board.t(),
  ids: %{
    required(Visualize.Chart.Builder.Store.id()) =>
      Visualize.Chart.Builder.Store.id()
  },
  outside: [Visualize.Chart.Builder.Store.id()]
}

What a board's import gives: the board re-keyed, the id table, and the masks.

provenance()

@type provenance() :: %{
  store: term(),
  exported_at: DateTime.t(),
  schema: pos_integer()
}

Where a bundle came from, when, and the schema version it was exported at, which an importer older than it refuses (spec/14 §9.1).

t()

@type t() :: %Visualize.Chart.Builder.Bundle{
  board: map() | nil,
  entries: [Visualize.Chart.Builder.Store.entry()],
  provenance: provenance()
}

A bundle: its provenance, its entries in dependency order, and — for one export_board/3 made — the board in its map form (spec/15 §2.1), else nil.

Functions

export(store, ids, source)

@spec export(
  Visualize.Chart.Builder.Store.store(),
  Visualize.Chart.Fragment.id() | [Visualize.Chart.Fragment.id()],
  term()
) :: t()

The closure of an id through a store: the entry, and every entry it refers to, transitively, each once, in dependency order — an entry after everything it refers to.

source names the store in the provenance; it is the host's to choose and the store is never asked. An id the store does not hold is skipped: it was a mask before export and stays one after import (§19.2).

export_board(store, board, source)

@spec export_board(Visualize.Chart.Builder.Store.store(), Visualize.Board.t(), term()) ::
  t()

A board as a bundle (spec/15 §11.1): the board's map form, the closure of every component its cells reference, and the closure of every stored theme the board or its components name, dependencies first, with provenance as export/3 gives it.

A component names a theme by its flattened design's theme; a variable there is read through the cell's cascade (spec/15 §5), which is how a board names one. A built-in name is not carried, nor one the store does not hold. A cell whose component the store does not hold is exported as it is, and import_board/3 reports it. No binding is carried: a binding names one host's feeds.

import_board(store, bundle)

@spec import_board(Visualize.Chart.Builder.Store.store(), t()) ::
  {:ok, imported()} | {:error, [Visualize.Board.error(), ...]}

As import_board/3 with [] options.

import_board(store, bundle, opts)

@spec import_board(Visualize.Chart.Builder.Store.store(), t(), keyword()) ::
  {:ok, imported()} | {:error, [Visualize.Board.error(), ...]}

A board bundle into a store (spec/15 §11.2): {:ok, %{board: board, ids: table, outside: ids}}, the board with every cell's ref rewritten to its component's new id, or {:error, errors}, every fault in the board's path shape.

Every check comes before any entry is put, so a refused bundle leaves the store as it was: the provenance's schema (spec/14 §9.1); the board read by Visualize.Board.from_map/2 under limits:; the entries' count and each entry's depth and items; the board validated with the bundle's entries as its store, a cell whose component the bundle does not carry being {:not_carried, id} at its ref; and each carried theme's name, which the store may not already give a different theme ({:theme_taken, name}). Then the entries go through the store's own import/2, which issues every new id, and a store's refusal is {:store, reason} at []. The board is returned, never put: where a host keeps its boards is its own.

Options