@koden/interval-manager

Shared interval ticker for TypeScript apps, with optional React bindings.

Install

npm install @koden/interval-manager

React bindings (if needed):

npm install react

Quick usage (core)

import { createIntervalManager } from "@koden/interval-manager";

const manager = createIntervalManager();

const unsubscribe = manager.subscribe(({ nowMs, tickCount }) => {
  console.log("tick", tickCount, nowMs);
});

manager.start();

// later
unsubscribe();
manager.stop();
manager.dispose();

React usage

import React from "react";
import {
  IntervalManagerProvider,
  useIntervalNow,
  useIntervalCountdown,
} from "@koden/interval-manager/react";

function Clock() {
  const nowMs = useIntervalNow();
  return <p>{new Date(nowMs).toLocaleTimeString()}</p>;
}

function OfferCountdown() {
  const targetMs = Date.now() + 60_000;
  const remainingMs = useIntervalCountdown(targetMs);
  return <p>{Math.ceil(remainingMs / 1000)}s left</p>;
}

export function App() {
  return (
    <IntervalManagerProvider>
      <Clock />
      <OfferCountdown />
    </IntervalManagerProvider>
  );
}

Environment defaults

The manager reads these environment values when created:

• USE_INTERVAL_KODEN=true|false
• USE_INTERVAL_SECONDS_KODEN=<seconds>

Parsing rules:

• USE_INTERVAL_KODEN is case-insensitive and trimmed.
• Only "true" and "false" are accepted. Any other value falls back to default (true).
• USE_INTERVAL_SECONDS_KODEN must be a finite positive number.
• Missing/invalid seconds fall back to 1.
• Valid seconds are clamped to a minimum of 1.
• Programmatic config (enabled, intervalSeconds) overrides env values.
• Runtime API can still update values via setEnabled(...) and setIntervalSeconds(...).

Example:

const manager = createIntervalManager({
  enabled: false,
  intervalSeconds: 5,
});

SSR notes

• createIntervalManager safely checks for process.env only when available.
• useIntervalNow uses useSyncExternalStore and provides a server snapshot.
• Prefer creating one manager instance per request boundary in SSR frameworks.

Migration notes

Replace many component-level setInterval calls with one shared manager:

1. Create one manager during app bootstrap.
2. Subscribe from places that need a periodic update.
3. Remove local timer setup/cleanup from components.
4. In React, expose it via IntervalManagerProvider and use hooks.

This reduces duplicate timers and keeps ticking behavior centralized.

API

Core:

• createIntervalManager(config?)
• start()
• stop()
• isRunning()
• getNow()
• subscribe(listener)
• setIntervalSeconds(seconds)
• setEnabled(enabled)
• dispose()

React:

• IntervalManagerProvider
• useIntervalManager()
• useIntervalNow()
• useIntervalCountdown(targetMs)