Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »

piral-feeds

0.12.1 • Public • Published

Piral Logo

Piral Feeds · GitHub License npm version tested with jest Gitter Chat

This is a plugin that only has a peer dependency to piral-core. What piral-feeds brings to the table is a set of Pilet API extensions that can be used with piral or piral-core.

By default, these API extensions are not integrated in piral, so you'd need to add them to your Piral instance.

Documentation

The following functions are brought to the Pilet API.

createConnector

Creates a new feed connector, which is an abstraction over a state container driven by the typical lifecycle of a data feed connection.

Returns a higher-order component for providing a data prop that reflects the current feed data.

Usage

::: summary: For pilet authors

You can use the createConnector function from the Pilet API to create a global container managed data feed inside the Piral instance.

There are two kind of calls. The simple variant just uses a callback to populate the data via a lazy loading mechanism.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
import { Page } from './Page';
 
export function setup(piral: PiletApi) {
  const connect = createConnector(() => fetch('http://example.com').then(res => res.json()));
  piral.registerPage('/sample', connect(Page));
}

The most powerful variant declares three different sections:

  1. initialize to declare how data should be loaded initially (e.g., by loading from some API) required
  2. connect to define how updates of the data should be retrieved (e.g., via a WebSocket connection) optional
  3. update to handle the patching of data (e.g., combining the current data with the data retrieved from a WebSocket connection) optional

If you specify connect we recommend to also define update.

Example use:

import { PiletApi } from '<name-of-piral-instance>';
import { Page } from './Page';
 
export function setup(piral) {
  const connect = createConnector({
    initialize() {
      return fetch('http://example.com').then(res => res.json());
    },
    connect(cb) {
      const ws = new WebSocket();
      ws.onmessage = e => cb(JSON.parse(e.data));
      return () => ws.close();
    },
    update(data, item) {
      return [...data, item];
    },
  });
  piral.registerPage('/sample', connect(({ data }) => <Page items={data} />));
}

Calling createConnector returns a higher-order component that injects a new prop called data into the component.

Furthermore two more options are available:

  • immediately optionally avoids lazy loading and fetches the data immediately.
  • reducers allows to extend the HOC with some actions triggering the provided reducer functions.

The latter can be used like in the following example:

import { PiletApi } from '<name-of-piral-instance>';
 
export function setup(piral: PiletApi) {
  const connect = piral.createConnector({
    initialize() {
      return Promise.resolve([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
    },
    update(data: Array<number>) {
      return data;
    },
    reducers: {
      shuffle(data) {
        return data.slice().sort(() => Math.random() - 0.5);
      },
    },
  });
 
  piral.registerPage(
    "/sample",
    connect(({ data }) => (
      <>
        <ul>
          {data.map((i) => (
            <li key={i}>{i}</li>
          ))}
        </ul>
        <button onClick={connect.shuffle}>Shuffle</button>
      </>
    ))
  );
}

:::

::: summary: For Piral instance developers

The provided library only brings API extensions for pilets to a Piral instance.

For the setup of the library itself you'll need to import createFeedsApi from the piral-feeds package.

import { createFeedsApi } from 'piral-feeds';

The integration looks like:

const instance = createInstance({
  // important part
  plugins: [createFeedsApi()],
  // ...
});

There are no options available.

:::

License

Piral is released using the MIT license. For more information see the license file.

Install

npm i piral-feeds

DownloadsWeekly Downloads

883

Version

0.12.1

License

MIT

Unpacked Size

55.7 kB

Total Files

37

Homepage

piral.io

Last publish

Collaborators

  • avatar