buzzcasting-storage

BuzzCasting Storage

This is a wrapper class to use multiple storage options with BuzzCasting.

BuzzCasting Social Media Wall & Dataviz More info.

Currently supported are: Local Storage, Session Storage, IDB Keyval, Dexie, Window object

Documentation

docs/ is typedoc-generated API reference (regenerated by npm run docs, overwritten every time — don't hand-edit it). Hand-written architecture guides live in documentation/ instead:

• documentation/architecture.md — the BuzzcastingStorageManager/Widget/BuzzcastingStorageReader pipeline, the subscribe → fetch → hash-diff → broadcast → re-read data flow, and why a Widget can only ever render cloud/series/messages data.
• documentation/storage-backends.md — the five interchangeable storage backends, the Dexie schema, and the staleness/expiry model (there isn't much of one).
• documentation/known-issues.md — confirmed bugs and inconsistencies in the current codebase (e.g. ApiClient.loadDashboards actually fetching the widgets endpoint, not a dashboards one) worth knowing about before you hit them yourself.
• documentation/moderation.md — hideMessage/hideLabels: a soft visible flag in Dexie plus a remote call for messages, a remote-only call with no local implementation at all for cloud labels, and the separate, deployment-time MODERATION enum that gates which messages are ever fetched in the first place.

Features

• Fully customized eslint configuration based on the config by Antfu
• Write tests quickly and conveniently with vitest
• Supports conventional commits
• Generate beautiful changelogs with changelogen
• GitHub CI for your build
• Ready configuration for renovatebot with renovate-config
• Library releases with just one command

Get started

This package has two entry points, used by two different kinds of consumer — see documentation/architecture.md for the full picture.

A rendered widget component (e.g. a cards-widget/series-widget/cloud-widget in buzzcasting-app) uses Widget, keyed off its own data-* attributes:

import { Widget } from 'buzzcasting-storage'
import type { IResponse } from 'buzzcasting-utils'

// element.dataset.{widget,dashboard,type} become the query; window.__bc.opts
// must already be set up by the host app (it supplies `presentation`).
const setData = (response: IResponse) => {
  if (!response.success) return
  // ...update component state from response.data
}

const widget = new Widget(element, [setData])
widget.subscribe() // registers with the app-level BuzzcastingStorageManager

Widget only supports series, cloud, and messages query types — nothing else (this is a hard architectural constraint, see documentation/architecture.md).

The host app itself (once, at startup) constructs the orchestrator every Widget rendezvouses with over a shared BroadcastChannel:

import { BuzzcastingStorageManager } from 'buzzcasting-storage'
import type { IStorageOptions } from 'buzzcasting-utils'

const options: IStorageOptions = {
  app: 'my-subdomain',
  version: 'v4',
  presentation: 'presentation_id',
  locale: 'en-US',
  bearer: 'bearer_token',
  storage: 'dexie', // the only backend actually exercised in production - see documentation/storage-backends.md
}

const storageManager = new BuzzcastingStorageManager(options)
storageManager.startBroadcastListener() // begins listening for widget SUBSCRIBE/UPDATE events

// on whatever interval/event the host app decides:
await storageManager.update()

Git Clone

git clone https://github.com/TouchFlows/buzzcasting-storage.git
cd buzzcasting-storage
pnpm install

Usage

The project contains the following scripts:

• dev - Start the development server
• build - Build for production
• release - Generate changelog and npm publish
• lint - Checks your code for any linting errors
• test - Run all tests
• test:watch - Run all tests with watch mode
• test:coverage - Run all tests with code coverage report
• prepare - Script for setting up husky hooks

Useful Links

• IndexedDB Reference

License

This template was created under the MIT License.