@stackonward/scheduler

Framework-independent, network-aware concurrency scheduling for browser resources. It provides priority queues, starvation-preventing aging, explicit release and cancellation, and injectable network probes.

Install

pnpm add @stackonward/scheduler

Usage

import { createResourceScheduler } from "@stackonward/scheduler";

const scheduler = createResourceScheduler();

async function loadResource() {
  const handle = scheduler.request("high");
  await handle.ready;
  try {
    await fetchResource();
  } finally {
    handle.release();
  }
}

Create one scheduler for the browser runtime that shares the resource budget. Call scheduler.dispose() when that runtime ends so the network listener and aging timer are removed.

Scheduling behavior

| Priority | Order | Aging | | ---------- | ------ | --------------------------------- | | critical | first | none | | high | second | none | | low | third | promotes to high after waiting | | idle | fourth | promotes to low, then to high |

The default concurrency ceiling is six on 4G or when the connection is unknown, four on 3G, and two on 2G, slow-2G, or data-saver connections. Inject probe and subscribeNetworkChange when the runtime supplies network state through another adapter.

Queued work starts only after handle.ready resolves. Call cancel() to remove queued work or release an active slot without waiting for the operation. Active handles automatically release their slot after 30 seconds, but callers should still release deterministically in finally.

Server behavior

When window is unavailable, request() returns an immediately ready no-op handle. The package does not impose browser concurrency policy on SSR work.

Public API

| Export | Purpose | | ----------------------------------------- | ----------------------------------------- | | createResourceScheduler | Create an isolated scheduler | | ResourceScheduler | request and dispose contract | | ResourceHandle | ready, release, and cancel contract | | ResourcePriority | Supported queue priorities | | NetworkProbe, NetworkChangeSubscriber | Replaceable network-state adapters |

Compatibility

• ESM with TypeScript declarations
• Modern browsers for default Network Information API integration
• Safe to import and call during SSR

License

MIT