Skip to content

About

Declarative, type-safe, offline-first solution for connectivity management for web apps.

Topics

Resources

Contributing

Stars

19 stars

Watchers

0 watching

Forks

Repository files navigation

connectivity-js

Declarative, type-safe connectivity detection and offline action queue for web apps.

Package Version Description
@connectivity-js/core NPM Version Framework-agnostic core — use with any framework or vanilla JS
@connectivity-js/react NPM Version React adapter
@connectivity-js/devtools NPM Version Framework-agnostic DevTools panel
@connectivity-js/react-devtools NPM Version React DevTools panel
  • Declarative: <Connectivity fallback={...}> for online/offline UI switching
  • Framework-agnostic: core has no framework dependency — works with vanilla JS, Vue, Svelte, and more
  • Type-safe: TInput and TResult fully inferred — no manual annotation
  • Auto-queue: offline actions are queued and flushed on reconnect
  • Deduplication: rapid saves collapsed — only the latest reaches the server
  • Retry: failed requests retried with configurable backoff

Note: The action queue is session-scoped (memory-backed). Pending actions are lost on page refresh or tab close. For durable delivery, implement server-side idempotency keys.

Quick Start

Core (framework-agnostic)

Works with vanilla JS/TS, Vue, Svelte, or any other environment.

import {
  ConnectivityClient,
  browserOnlineDetector,
  heartbeatDetector,
  actionOptions,
} from '@connectivity-js/core';

// 1. Create client and start detection
const client = new ConnectivityClient({
  detectors: [
    browserOnlineDetector(),
    heartbeatDetector({ url: '/api/health' }),
  ],
  gracePeriodMs: 3_000,
});
client.start();

// 2. Subscribe to connectivity state
client.subscribe((state, transition) => {
  if (transition?.to === 'offline') {
    document.getElementById('banner')?.classList.add('visible');
  }
  if (transition?.to === 'online') {
    document.getElementById('banner')?.classList.remove('visible');
  }
});

// 3. Define and execute actions
// request accepts any HTTP client — fetch, ky, axios, etc.
const save = actionOptions({
  actionKey: 'save',
  request: (input: { id: string; data: string }) => api.save(input),
  dedupeKey: (input) => input.id,
  whenOffline: 'queue',
});

const result = await client.execute(save, { id: '1', data: 'hello' });
if (result.enqueued) {
  console.log('Offline — queued:', result.jobId);
} else {
  console.log('Succeeded:', result.result);
}

// 4. Clean up
client.destroy();

React Adapter

import {
  ConnectivityProvider,
  Connectivity,
  browserOnlineDetector,
  useConnectivity,
  useAction,
} from '@connectivity-js/react';

// 1. Wrap your app
function App() {
  return (
    <ConnectivityProvider
      detectors={[browserOnlineDetector()]}
      gracePeriodMs={3_000}
    >
      <Connectivity fallback={<div>You're offline</div>} delayMs={3_000}>
        <MyApp />
      </Connectivity>
    </ConnectivityProvider>
  );
}

// 2. Display status
function StatusBadge() {
  const { status } = useConnectivity();
  if (status === 'offline') return <Badge>Offline</Badge>;
  return <Badge>Online</Badge>;
}

// 3. Execute actions
function SaveButton({ id, data }: { id: string; data: string }) {
  const { execute, pendingCount } = useAction({
    actionKey: 'save',
    request: (input: { id: string; data: string }) => api.save(input),
    dedupeKey: (input) => input.id,
  }, {
    onSuccess: () => toast.success('Saved'),
    onEnqueued: () => toast.info('Queued'),
  });

  return (
    <button onClick={() => execute({ id, data })}>
      Save {pendingCount > 0 && `(${pendingCount})`}
    </button>
  );
}

Contributing

We welcome contributions from everyone in the community. Read the detailed contribution guide.

Check out the docs for installation guides, usage examples, API reference, and more.

License

See LICENSE for more information.

MIT © minseong0324

About

Declarative, type-safe, offline-first solution for connectivity management for web apps.

Topics

Resources

Contributing

Stars

19 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages