treble-hook
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.13 • Public • Published
    treble-hook

    Simple, lightweight state management library for ReactJS with zero dependencies, weighing in at just under 900 bytes (gzip).


    version Build Status downloads MIT License
     

    - IMPORTANT: Upgrading from v1 to v2 includes breaking changes; see API below for new interfaces.

    Installation

    yarn add treble-hook

    or

    npm install --save treble-hook


    Quick Start

    import trebleHook, { usePub, useSub } from 'treble-hook'
     
    // Welcome.jsx
    export default function Welcome() {
      const guestName = useSub('guest')
     
      return (
        <h3>Welcome to treble-hook, {guestName || ''}!</h3>
      )
    }
     
    // GuestEntry.jsx
    export default function GuestEntry() {
      const pubGuestName = usePub('guest')
     
      return (
        <div>
          <input
            type="text"
            onChange={(e) => { pubGuestName(e.target.value) }}
          />
        </div>
      )
    }
     
    // App.jsx
    export default function App() {
     
      trebleHook.addTopic('guest', '')
     
      const GuestPublisher = trebleHook.getPublisher()
     
      return (
        <GuestPublisher>
          <GuestEntry />
          <br />
          <Welcome />
        </GuestPublisher>
      )
    }

    Live Examples on Codesandbox


    API

    trebleHook.addTopic()

    Adds a new topic that can be published and subscribed to.

    addTopic<T>(topicNamestring, defaultValueT, initWithSessionStorage = false)void
    • topicName is the identifier for the topic and must be unique within the application.
    • defaultValue will be used as the initial state value for respective topic.
    • initWithSessionStorage determines whether to retrieve the topic's initial state from session storage. If true, then all subsequent published state changes will also be stored in sessions state for the app. This is helpful to ensure consistent state between any routes that require hard reloads.

    Example:

    import trebleHook from 'treble-hook'
     
    trebleHook.addTopic('apples', 25)
    trebleHook.addTopic('organges', 42)
    trebleHook.addTopic('carrots', 100)

    trebleHook.getPublisher()

    Returns a TrebleHookPublisher JSX element that manages publications for given topics. The Publisher JSX should be placed high in the component tree (ancestral to all components that interact with the respective publisher state).

    getPublisher(topics?: string[])TrebleHookPublisher (JSX.Element)
    • topics is the array of topic names contextual to this publisher that have been added using the addTopic method. If no topics are passed in then all topics will be included in the returned publisher.

    Example:

    import React from 'react'
    import trebleHook from 'treble-hook'
     
    const FruitCountPublisher = trebleHook.getPublisher(['apples', 'oranges'])
     
    return (
      <FruitCountPublisher>
        <FruitStand />
      </FruitCountPublisher>
    )

    usePubSub

    A hook that subscribes a component to a topic with capability to publish. The hook returns a tuple that is similar to the tuple returned from useState where the first element is the topic's current state value and the second element is the method to publish a new state value for the topic.

    usePubSub<T>(topicstring)PubSubTuple<T>
    • topic is the unique topic name to subscribe to.

    Example:

    import React from 'react'
    import { usePubSub } from 'treble-hook'
     
    function FruitTable() {
      const [apples] = usePubSub<number>('apples')
      const [oranges] = usePubSub<number>('oranges')
     
      return (
        <div>
          <h3>Apple count: {apples}</h3>
          <h3>Orange count: {oranges}</h3>
        </div>
      )
    }
     
    function FruitVendor() {
      const [apples, pubApples] = usePubSub<number>('apples')
      const [oranges, pubOranges] = usePubSub<number>('oranges')
     
      return (
        <div>
          <button
            disabled={apples === 0}
            onClick={() => {
              pubApples(apples - 1)
            }}
          >
            Sell an apple
          </button>
          <button
            disabled={oranges === 0}
            onClick={() => {
              pubOranges(oranges - 1)
            }}
          >
            Sell an orange
          </button>
        </div>
      )
    }
     
    function FruitStand() {
      <FruitTable />
      <FruitVendor />
    }

    usePub

    A hook returning a function that publishes to a topic.

    IMPORTANT: Even though this hook only returns the publish function, it will still cause a re-render whenever a value for respective topic is published outside the scope of this component (i.e. when published from another component).

    usePub<T>(topicstring): (value: T) => void

    Example:

    import { usePub } from 'treble-hook'
     
    function FruitVendor() {
      const pubApples = usePub<number>('apples')
     
      return (
        <div>
          <button
            onClick={() => {
              pubApples(100)
            }}
          >
            Reset apples
          </button>
        </div>
      )
    }

    useSub

    A hook returning a function that subscribes to a topic.

    useSub<T>(topicstring)T

    Example:

    import { useSub } from 'treble-hook'
     
    function FruitVendor() {
      const apples = useSub<number>('apples')
     
      return (
        <div>
          Apply quantity: {apples}
        </div>
      )
    }

    Liscense

    MIT

    Install

    npm i treble-hook

    DownloadsWeekly Downloads

    42

    Version

    2.0.13

    License

    MIT

    Unpacked Size

    17.7 kB

    Total Files

    8

    Last publish

    Collaborators

    • rollercodester
    • warmbowski