Reactium SDK Core

Core subset of Reactium SDK singleton and named exports.

Install

npm install --save @atomic-reactor/reactium-sdk-core

Usage

NPM Module

import { Zone, useHookComponent } from '@atomic-reactor/reactium-sdk-core';

Reactium projects

// As above or with some enhhancements patched in from reactium-core workspace:
import { Zone, useHookComponent } from '@atomic-reactor/reactium-core/sdk';

API Description

This project is best used with Reactium but can also be used independently. See the API documentation.

Note: The API documentation link above is written with lots of examples to by used inside a Reactium app projects, but most examples will work if you import from the NPM module directly.

SDK Objects

The primary SDK objects in this library are:

• Cache: For controlling runtime object cache in node or browser
• Handle: Registry that manages React handle references
• Hook: Registry for callbacks for async/sync "hook" invocations.
• Component: Registry for replaceable React component string tokens.
• Pulse: Registry for running recurring processes over time (like cron for React)
• Zone: Registry for React components to render in "rendering zones" (i.e. <Zone /> component)
• Prefs: Allows you to manipulate local storage from React very quickly and easily.

React Hooks

This SDK comes with a number of React hooks:

• useHookComponent: Use a React component registers to Component registry. Allows you to create string token component that can be implemented elsewhere.
• useDerivedState: Tool to managed derived React state from props (if you must).
• useEventEffect: Quickly and easily add and remove event listeners.
• useFocusEffect: Get a true/false state when element is focused.
• useAsyncEffect: Like useEffect, but with built-in protection for setting state async.
• useEventRefs: Like useRefs, but also an EventTarget for event streaming reference changes.
• useFocusEffect: Used to focus a child component on render
• useFulfilledObject: Helps you aggregate async data in React when all conditions are met / ready.
• useHandle: Use a registered imperative React handle by handle id.
• useHookComponent: Used to get re-registered Components and use them in your Component with ease.
• useIsContainer: Determines if the element is a child of the container. Useful for traversing the DOM to find out if an event or action happened within the specified container.
• useRefs: Manage multiple refs easily.
• useRegisterHandle: Register an imperative React handle that can be used anywhere in the app.
• useRegisterSyncHandle: Register an imperative React handle that is also a sync state management object. (See useSyncState)
• useScrollToggle: Facilitates enabling or disabling body scrolling in the browser.
• useSelectHandle: Allows you to "select" state from a registered sync handle, and rerender your React component when the selection changes.
• useStatus: Helper hook for walking through enumerated states.
• useSyncHandle: Attach your component to a registered imperative handle.
• useSyncState: A drop in replacement for useState that avoids async state update getting out of sync with your render. Also an EventTarget for event streaming state updates.

Browser / App Utilities

• Registry: A generic subscribable registry class.
• registryFactory: A function that quickly create Registry objects.
• cxFactory: A function that will build a React className namespace, for easily passing a CSS context down through components.
• splitParts: A function that makes it easy to convert a tokenized string into a map of React components.
• isWindow: A function that detects the presence of a global "window" object.
• isServer: A function that detects if running on node.js (as opposed to in browser)
• isServerWindow: A functions for determining if the window object is actually on the server (using JSDOM) in Reactium.
• isElectronWindow: A function for determining if the environment is actually Electron (not the web browser)

React Components

• Zone: A "rendering zone" for other components to dynamically render.
• HookComponent: An "abstract component" which can be implemented elsewhere.

ES Module Exports

As a reference, here is a full list of the library esmodule exports. (Just to make you aware of what is available in your import statements)

The default import includes everything, but you may also import just core modules (appropriate for node), or browser modules (appropriate for React).

From @atomic-reactor/reactium-sdk-core/browser:

[Module: null prototype] {
  BREAKPOINTS_DEFAULT: { xs: 640, sm: 990, md: 1280, lg: 1440, xl: 1600 },
  Component: RegisteredComponents [EventTarget] {
    listeners: {},
    op: {
      has: [Function: bound ],
      ensureExists: [Function: bound ],
      set: [Function: bound ],
      insert: [Function: bound ],
      empty: [Function: bound ],
      push: [Function: bound ],
      coalesce: [Function: bound ],
      get: [Function: bound ],
      del: [Function: bound del],
      withInheritedProps: [Function: bound objectPath]
    },
    options: { noMerge: true },
    _addEventListener: [Function: bound addEventListener],
    addEventListener: [Function (anonymous)],
    [Symbol(INITIAL_STATE)]: {},
    [Symbol(STATE)]: { Zone: [Function: Zone] }
  },
  ComponentEvent: [class ComponentEvent extends CustomEvent],
  ComponentTarget: [class ComponentTarget extends EventTarget],
  Fullscreen: FullscreenClass {
    initialized: false,
    update: [Function: update],
    isExpanded: [Function (anonymous)],
    isCollapsed: [Function (anonymous)],
    collapse: [Function (anonymous)],
    expand: [AsyncFunction (anonymous)],
    toggle: [Function (anonymous)],
    element: HTMLHtmlElement {}
  },
  FullscreenClass: [class FullscreenClass],
  Handle: Handle { handles: { BodyScroll: [Object] }, subscriptions: {} },
  HookComponent: [Function: HookComponent],
  PassThroughZone: [Function: PassThroughZone],
  Prefs: PrefsClass {
    storageKey: 'ar-prefs',
    clear: [Function (anonymous)],
    get: [Function (anonymous)],
    set: [Function (anonymous)]
  },
  PrefsClass: [class PrefsClass],
  ReactiumSyncState: [class ReactiumSyncState extends EventTarget],
  RegisteredComponents: [class RegisteredComponents extends ReactiumSyncState],
  SimpleZone: [Function: SimpleZone],
  SplitParts: [class SplitParts] { splitter: [Function: splitter] },
  Zone: [Function: Zone],
  ZoneRegistry: Zones {
    defaultControls: { components: [], controls: [Object] },
    [Symbol(INITIALIZED)]: false,
    [Symbol(ZONES)]: { subscribers: [Object], components: [Object], controls: [Object] },
    [Symbol(UNSUBSCRIBE)]: [Function (anonymous)]
  },
  Zones: [class Zones],
  __esModule: true,
  breakpoint: [Function: breakpoint],
  breakpoints: [Function: breakpoints],
  conditionalDocument: [Function: conditionalDocument],
  conditionalWindow: [Function: conditionalWindow],
  cxFactory: [Function: cxFactory],
  default: {
    cxFactory: [Getter],
    ComponentEvent: [Getter],
    ComponentTarget: [Getter],
    FullscreenClass: [Getter],
    Fullscreen: [Getter],
    Handle: [Getter],
    PrefsClass: [Getter],
    Prefs: [Getter],
    ReactiumSyncState: [Getter],
    forwardRefNoop: [Getter],
    RegisteredComponents: [Getter],
    Component: [Getter],
    SplitParts: [Getter],
    splitParts: [Getter],
    useAsyncEffect: [Getter],
    useDerivedState: [Getter],
    isTarget: [Getter],
    useEventEffect: [Getter],
    useFocusEffect: [Getter],
    useFulfilledObject: [Getter],
    useHandle: [Getter],
    useHookComponent: [Getter],
    useIsContainer: [Getter],
    useRefs: [Getter],
    useRegisterHandle: [Getter],
    useRegisterSyncHandle: [Getter],
    useScrollToggle: [Getter],
    useSelectHandle: [Getter],
    useStatus: [Getter],
    useSyncHandle: [Getter],
    useSyncState: [Getter],
    conditionalWindow: [Getter],
    conditionalDocument: [Getter],
    isWindow: [Getter],
    isElectronWindow: [Getter],
    isBrowserWindow: [Getter],
    BREAKPOINTS_DEFAULT: [Getter],
    breakpoints: [Getter],
    breakpoint: [Getter],
    Zone: [Getter],
    SimpleZone: [Getter],
    PassThroughZone: [Getter],
    HookComponent: [Getter],
    Zones: [Getter],
    ZoneRegistry: [Getter]
  },
  forwardRefNoop: {
    '$$typeof': Symbol(react.forward_ref),
    render: [Function (anonymous)]
  },
  isBrowserWindow: [Function: isBrowserWindow],
  isElectronWindow: [Function: isElectronWindow],
  isTarget: [Function: isTarget],
  isWindow: [Function: isWindow],
  splitParts: [Function: splitParts],
  useAsyncEffect: [Function: useAsyncEffect],
  useDerivedState: [Function: useDerivedState],
  useEventEffect: [Function: useEventEffect],
  useFocusEffect: [Function: useFocusEffect],
  useFulfilledObject: [Function: useFulfilledObject],
  useHandle: [Function: useHandle],
  useHookComponent: [Function: useHookComponent],
  useIsContainer: [Function: useIsContainer],
  useRefs: [Function: useRefs],
  useRegisterHandle: [Function: useRegisterHandle],
  useRegisterSyncHandle: [Function: useRegisterSyncHandle],
  useScrollToggle: [Function: useScrollToggle],
  useSelectHandle: [Function: useSelectHandle],
  useStatus: [Function: useStatus],
  useSyncHandle: [Function: useSyncHandle],
  useSyncState: [Function: useSyncState]
}

From @atomic-reactor/reactium-sdk-core/core:

[Module: null prototype] {
  Cache: MemoryCache {
    _subscribers: {},
    _subscribedPaths: {},
    set: [Function: put],
    _mc: Cache {
      put: [Function (anonymous)],
      del: [Function (anonymous)],
      clear: [Function (anonymous)],
      get: [Function (anonymous)],
      size: [Function (anonymous)],
      memsize: [Function (anonymous)],
      debug: [Function (anonymous)],
      hits: [Function (anonymous)],
      misses: [Function (anonymous)],
      keys: [Function (anonymous)],
      exportJson: [Function (anonymous)],
      importJson: [Function (anonymous)]
    }
  },
  Enums: {
    cache: { settings: 90000 },
    priority: {
      '0': 'neutral',
      '500': 'low',
      '1000': 'lowest',
      core: -2000,
      '-2000': 'core',
      highest: -1000,
      '-1000': 'highest',
      high: -500,
      '-500': 'high',
      neutral: 0,
      low: 500,
      lowest: 1000
    }
  },
  Hook: HookSDK {
    action: { sync: [Object], async: {} },
    actionIds: { '@reactium-file-tag': 'sync.@reactium.@reactium-file-tag' },
    domains: { '@reactium': [Object] },
    flush: [Function (anonymous)],
    unregister: [Function (anonymous)],
    unregisterDomain: [Function (anonymous)],
    _register: [Function (anonymous)],
    list: [Function (anonymous)],
    _actions: [Function (anonymous)],
    run: [Function (anonymous)],
    runSync: [Function (anonymous)]
  },
  MemoryCache: [class MemoryCache],
  NotificationTypes: {
    REGISTER: 'register',
    UNREGISTER: 'unregister',
    PROTECT: 'protect',
    UNPROTECT: 'unprotect',
    BAN: 'ban',
    UNBAN: 'unban',
    CLEANUP: 'cleanup',
    FLUSH: 'flush'
  },
  Priority: {
    '0': 'neutral',
    '500': 'low',
    '1000': 'lowest',
    core: -2000,
    '-2000': 'core',
    highest: -1000,
    '-1000': 'highest',
    high: -500,
    '-500': 'high',
    neutral: 0,
    low: 500,
    lowest: 1000
  },
  Pulse: PulseSDK {
    Task: null,
    [Symbol(6a45d4c2-5e9e-4a4b-9eb0-81ca2bf8bb8d)]: {},
    [Symbol(718e6d8e-4c2c-4124-b754-701aee955261)]: {}
  },
  PulseTask: [class PulseTask] {
    ENUMS: {
      ERROR: [Object],
      DEBUG: false,
      DEFAULT: [Object],
      STATUS: [Object]
    }
  },
  PulseTaskError: [class PulseTaskError extends Error],
  Registry: [class Registry] { MODES: { HISTORY: 'HISTORY', CLEAN: 'CLEAN' } },
  RegistryModes: { HISTORY: 'HISTORY', CLEAN: 'CLEAN' },
  Server: {
    Middleware: Registry {
      __name: 'ExpressMiddleware',
      __idField: 'name',
      __registered: [],
      __protected: {},
      __unregister: {},
      __banned: {},
      __subscribers: {},
      __mode: 'CLEAN'
    }
  },
  __esModule: true,
  abbreviatedNumber: [Function: abbreviatedNumber],
  annotationsFactory: [Function: annotationsFactory],
  create: [Function: registryFactory],
  default: {
    Priority: [Getter],
    Enums: [Getter],
    Hook: [Getter],
    MemoryCache: [Getter],
    Cache: [Getter],
    abbreviatedNumber: [Getter],
    PulseTaskError: [Getter],
    PulseTask: [Getter],
    Pulse: [Getter],
    RegistryModes: [Getter],
    NotificationTypes: [Getter],
    Registry: [Getter],
    registryFactory: [Getter],
    create: [Getter],
    Server: [Getter],
    annotationsFactory: [Getter]
  },
  registryFactory: [Function: registryFactory]
}