ua-outages 0.1.1 → 0.2.0

package/README.md

@@ -40,7 +40,7 @@ nextOutage(schedule.days) // { from: '2026-11-05T19:30:00+02:00', to: '2026-11-0
 | `donetsk`         | Донецька                | ДТЕК Донецькі електромережі             | schedule page + /ua/ajax (same provider as Odesa)              | ⚠️ code ready | ⚠️ code ready | the site answers automated clients with a bot check, so requests come back `blocked`; untested against live data | [dtek-dem.com.ua](https://www.dtek-dem.com.ua/ua/shutdowns)                                              | [dtek-dem.com.ua](https://www.dtek-dem.com.ua/ua/shutdowns)                                  |
 | `lviv`            | Львівська               | Львівобленерго                          | api.loe.lviv.ua, power-api.loe.lviv.ua                         | ✅            | ✅            |                                                                                                                  | [poweron.loe.lviv.ua](https://poweron.loe.lviv.ua/)                                                      | [poweron.loe.lviv.ua](https://poweron.loe.lviv.ua/)                                          |
 | `ternopil`        | Тернопільська           | Тернопільобленерго                      | api-poweron.toe.com.ua                                         | ✅            | ✅            | schedule read per group via a reference address                                                                  | [poweron.toe.com.ua](https://poweron.toe.com.ua/)                                                        | [poweron.toe.com.ua](https://poweron.toe.com.ua/)                                            |
-| `zakarpattia`     | Закарпатська            | Закарпаттяобленерго                     | api-outage-zakarpat-energy.inneti.net                          | ✅ / image    | ✅            | no outages while no picture is published; a published picture is reported as `unsupported`                       | [zakarpat.energy](https://zakarpat.energy/customers/break-in-electricity-supply/schedule/)               | [outage.zakarpat.energy](https://outage.zakarpat.energy/schedule_queues)                     |
+| `zakarpattia`     | Закарпатська            | Закарпаттяобленерго                     | api-outage-zakarpat-energy.inneti.net                          | ✅ / image    | ✅            | groups `unknown` while no picture is published; a published picture is reported as `unsupported`                 | [zakarpat.energy](https://zakarpat.energy/customers/break-in-electricity-supply/schedule/)               | [outage.zakarpat.energy](https://outage.zakarpat.energy/schedule_queues)                     |
 | `ivano-frankivsk` | Івано-Франківська       | Прикарпаттяобленерго                    | be-svitlo.oe.if.ua                                             | ✅            | ✅            | full address only, no autocomplete                                                                               | [svitlo.oe.if.ua](https://svitlo.oe.if.ua/)                                                              | [svitlo.oe.if.ua](https://svitlo.oe.if.ua/)                                                  |
 | `chernivtsi`      | Чернівецька             | Чернівціобленерго                       | schedule page + district directories                           | ✅            | ✅            | groups numbered 1–12                                                                                             | [oblenergo.cv.ua](https://oblenergo.cv.ua/shutdowns/)                                                    | [oblenergo.cv.ua](https://oblenergo.cv.ua/shutdowns-search/)                                 |
 | `rivne`           | Рівненська              | Рівнеобленерго                          | schedule page                                                  | ✅            | —             | addresses only in PDF                                                                                            | [roe.vsei.ua](https://www.roe.vsei.ua/disconnections)                                                    | —                                                                                            |
@@ -56,7 +56,7 @@ nextOutage(schedule.days) // { from: '2026-11-05T19:30:00+02:00', to: '2026-11-0
 | `zaporizhzhia`    | Запорізька              | Запоріжжяобленерго                      | news page                                                      | ✅            | —             | no web lookup                                                                                                    | [zoe.com.ua](https://www.zoe.com.ua/outage/)                                                             | [Telegram bot](https://t.me/esozoebot)                                                       |
 | `mykolaiv`        | Миколаївська            | Миколаївобленерго                       | off.energy.mk.ua API                                           | ✅            | ✅            |                                                                                                                  | [off.energy.mk.ua](https://off.energy.mk.ua/)                                                            | [off.energy.mk.ua](https://off.energy.mk.ua/)                                                |
 
-**АТ «Укрзалізниця»** is a distribution operator too: homes near stations and along the lines are wired to the railway's grid and get its own schedule, which differs from the oblenergo's. It has one region per oblast page on [uz.gov.ua](https://www.uz.gov.ua/about/activity/electropostachannia/electro_consumers/temporary_shutdown/grafikiobmezhen/): `uz-kyiv`, `uz-kyiv-region`, `uz-dnipro`, … (`uz-<region id>`), and two branches each in Vinnytsia (`uz-vinnytsia`, `uz-vinnytsia-odesa`) and Sumy (`uz-sumy`, `uz-sumy-south`). Today's schedule only, read from the HTML table; a page with no table means no outages. The page also lists each group's addresses (no lookup yet).
+**АТ «Укрзалізниця»** is a distribution operator too: homes near stations and along the lines are wired to the railway's grid and get its own schedule, which differs from the oblenergo's. It has one region per oblast page on [uz.gov.ua](https://www.uz.gov.ua/about/activity/electropostachannia/electro_consumers/temporary_shutdown/grafikiobmezhen/): `uz-kyiv`, `uz-kyiv-region`, `uz-dnipro`, … (`uz-<region id>`), and two branches each in Vinnytsia (`uz-vinnytsia`, `uz-vinnytsia-odesa`) and Sumy (`uz-sumy`, `uz-sumy-south`). Today's schedule only, read from the HTML table; a page with no table publishes nothing, so every group comes back `unknown` for today. The page also lists each group's addresses (no lookup yet).
 
 **Not covered**
 
@@ -68,7 +68,7 @@ nextOutage(schedule.days) // { from: '2026-11-05T19:30:00+02:00', to: '2026-11-0
 Луганська область and Crimea are not covered. "today" means the operator publishes only the current day. "⚠️ code ready" means the provider is implemented but the operator currently blocks automated requests. "image" means the schedule is read from the table picture the operator publishes.
 <!-- regions:end -->
 
-"Address" means the SDK can turn an address into a group. Zakarpattia publishes its schedule only as a picture: while none is published `getSchedules` returns no groups (no outages announced); once one is, it throws `unsupported` with the picture's address. Its address lookup works either way.
+"Address" means the SDK can turn an address into a group. Zakarpattia publishes its schedule only as a picture: while none is published `getSchedules` lists its groups as `unknown` (not "no outages"); once one is, it throws `unsupported` with the picture's address. Its address lookup works either way.
 
 ### Why some regions are missing
 
@@ -95,14 +95,14 @@ The same option works for proxies, caching, logging and tests. When an operator
 
 ### `new OutageClient(options?)`
 
-| option       | default                  |                                                                                                                          |
-| ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `cacheTtlMs` | `300000`                 | Reuse a region's schedule for this long. `0` turns caching off. Concurrent requests for one region share a single fetch. |
-| `timeoutMs`  | `15000`                  | Per request.                                                                                                             |
-| `retries`    | `1`                      | Extra attempts after a network error or a 5xx.                                                                           |
-| `fetch`      | `globalThis.fetch`       | Bring your own (proxy, logging, tests).                                                                                  |
-| `userAgent`  | `ua-outages (+repo url)` |                                                                                                                          |
-| `providers`  | built-in                 | Replace or extend the regions.                                                                                           |
+| option       | default                  |                                                                                                                                                                         |
+| ------------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cacheTtlMs` | `300000`                 | Reuse a region's schedule for this long. `0` turns caching off. Concurrent requests for one region share a single fetch (except calls with a `signal`, see Cancelling). |
+| `timeoutMs`  | `15000`                  | Per request.                                                                                                                                                            |
+| `retries`    | `1`                      | Extra attempts after a network error or a 5xx. A bot-check page is never retried, whatever its status.                                                                  |
+| `fetch`      | `globalThis.fetch`       | Bring your own (proxy, logging, tests).                                                                                                                                 |
+| `userAgent`  | `ua-outages (+repo url)` |                                                                                                                                                                         |
+| `providers`  | built-in                 | Replace or extend the regions.                                                                                                                                          |
 
 ### Schedules
 
@@ -119,6 +119,44 @@ A `DaySchedule` is `{ date: 'YYYY-MM-DD', status, intervals }`:
 
 `updatedAt` is when the operator last changed the schedule, when the source says so.
 
+#### "No outages" vs "nothing published"
+
+The SDK never turns silence into "no outages": a group with no cells, a group named without times ("1.1: графік уточнюється") or a source that publishes nothing comes back `unknown`. Read a result like this:
+
+| you get                                          | it means                                                                                                                                    |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| a day with `status: 'no-outages'`                | The operator said there are no outages for that group that day (a cancellation notice, or a published schedule with nothing in that group). |
+| a day with `status: 'scheduled'`, no `intervals` | A schedule is in force for that day and has no outage for that group.                                                                       |
+| a day with `status: 'emergency'`                 | Emergency outages: the hourly schedule doesn't apply, power may go off at any time. Published, but not "no outages".                        |
+| a day with `status: 'unknown'`                   | Nothing is published for that group and day. Not "no outages".                                                                              |
+| every day of every group `unknown`               | The operator publishes nothing right now. Regions with a fixed set of groups keep listing them (e.g. Sumy marks every group "no data").     |
+| `groups: []`, `schedules: {}`                    | The operator publishes nothing right now, and its groups come only with a schedule (e.g. YASNO, DTEK). The same as all `unknown`.           |
+| a missing date                                   | Not published. Most operators publish today and, from the evening, tomorrow.                                                                |
+
+So "no outages" is only ever `no-outages` days or `scheduled` days without intervals. `emergency` means outages without a schedule; anything else (`unknown`, a missing date, no groups) should read as "the schedule isn't published", with a link to the operator's website. `stateAt()` returns `'unknown'` for `unknown` and `emergency` days.
+
+**Upgrading from 0.1.1:** `groups: []` used to be documented as "no outages" for some regions (Zakarpattia, the railway pages). It never means that now, and Sumy, Lviv, Zakarpattia, Ivano-Frankivsk, Ternopil, Mykolaiv, Zaporizhzhia and the railway pages list their groups as `unknown` instead when nothing is published. If your code shows "no outages" for an empty `groups` list, change it to something like:
+
+```ts
+const day = schedule.schedules[group]?.find((d) => d.date === kyivDate())
+if (!day || day.status === 'unknown') show('Графік не опубліковано')
+else if (day.status === 'emergency') show('Аварійні відключення, без графіка')
+else if (day.intervals.length === 0)
+  show('Відключень немає') // 'no-outages', or 'scheduled' without outages
+else showIntervals(day.intervals)
+```
+
+#### Cancelling
+
+```ts
+// stop as soon as your own deadline passes
+const s = await outages.getSchedules('sumy', { fresh: true, signal: AbortSignal.timeout(20_000) })
+```
+
+`getSchedules`, `getSchedule` and `healthCheck` take a `signal`. When it aborts, the call rejects right away with the signal's reason (an `AbortError` by default, not an `OutageError`). The work that call started is stopped: its request in flight is cancelled, and nothing more is sent to the operator for it, no further groups, pages or retries. With a `Promise.race` cap of your own, pass a signal too, otherwise the losing call keeps running in the background.
+
+Work shared with other callers keeps going for them: a call with a signal that is answered from the cache, or that waits for a session another call is opening, just stops waiting. Shared work is cancelled only when every caller waiting for it has given up. To keep one caller's cancellation from reaching others, a call with a signal doesn't share its own fetch through the cache while it runs (its result is cached when it arrives). Address search doesn't take a signal yet.
+
 ### Schedules published as pictures
 
 Volyn publishes the schedule only as a table image, and Khmelnytskyi does when it doesn't post it as text on its schedule page (the text wins for its date). The SDK reads those itself: it decodes the PNG, finds the grid and classifies each cell by colour, with no dependencies. When an operator posts a text announcement as an image under the same date, it is skipped. A colour the SDK doesn't know is reported as a `parse` error instead of being guessed.
@@ -177,7 +215,7 @@ const report = await outages.healthCheck({ address: true })
 // { ok, checkedAt, regions: [{ region, status: 'ok' | 'stale' | 'empty' | 'error', latencyMs, groups, updatedAt, message, address }] }
 ```
 
-- `empty`: the source works but publishes nothing right now. Usually it means there are no outages.
+- `empty`: the source works but publishes nothing right now (no groups, or every day `unknown`). Often there are no outages then, but the SDK can't tell.
 - `stale`: the schedule hasn't changed for `staleAfterHours` (default 72).
 - `error`: a network failure, a bot check (`blocked`), or a format change (`parse`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ua-outages",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "TypeScript SDK for Ukrainian power outage schedules: find your outage group by address and get schedules straight from the grid operators.",
   "keywords": [
     "ukraine",

package/src/client.ts

@@ -18,7 +18,7 @@ import type {
   RegionSchedule,
   Street,
 } from './types.js'
-import { mapLimit } from './util.js'
+import { abortable, mapLimit } from './util.js'
 
 export interface OutageClientOptions extends HttpOptions {
   /** How long fetched schedules are reused, default 5 min. 0 disables the cache. */
@@ -38,6 +38,8 @@ export interface HealthCheckOptions {
   staleAfterHours?: number
   /** Parallel requests, default 6 */
   concurrency?: number
+  /** Cancels the check: no further regions are fetched and the call rejects with the signal's reason */
+  signal?: AbortSignal
 }
 
 export interface HealthReport {
@@ -60,7 +62,9 @@ export class OutageClient {
   private readonly ctx: ProviderContext
   private readonly providers: ReadonlyMap<RegionId, Provider>
   private readonly cacheTtlMs: number
-  private readonly cache = new Map<RegionId, { at: number; value: Promise<RegionSchedule> }>()
+  private readonly cache = new Map<RegionId, { at: number; seq: number; value: Promise<RegionSchedule> }>()
+  /** Fetches started, so a slower older one never replaces a newer one in the cache */
+  private seq = 0
   private readonly searchCache = new Map<string, { at: number; value: Promise<unknown[]> }>()
 
   constructor(opts: OutageClientOptions = {}) {
@@ -90,22 +94,45 @@ export class OutageClient {
 
   // --- schedules ---
 
-  /** All groups of a region. */
-  async getSchedules(region: RegionId, opts: { fresh?: boolean } = {}): Promise<RegionSchedule> {
+  /**
+   * All groups of a region.
+   *
+   * `signal` cancels the call: it rejects with the signal's reason right away and sends no
+   * further requests to the operator (the one in flight is aborted too).
+   */
+  async getSchedules(region: RegionId, opts: ScheduleOptions = {}): Promise<RegionSchedule> {
     const p = this.provider(region)
+    const { signal } = opts
+    signal?.throwIfAborted()
     const hit = this.cache.get(region)
     const now = Date.now()
-    if (!opts.fresh && hit && now - hit.at < this.cacheTtlMs) return hit.value
-    const value = p.getSchedules(this.ctx)
+    if (!opts.fresh && hit && now - hit.at < this.cacheTtlMs) return abortable(hit.value, signal)
+    const value = p.getSchedules(this.context(signal))
+    const entry = { at: now, seq: ++this.seq, value }
     if (this.cacheTtlMs > 0) {
-      this.cache.set(region, { at: now, value })
-      value.catch(() => this.cache.delete(region))
+      if (signal) {
+        // a cancellable call isn't shared while it runs, so another caller never inherits its
+        // cancellation; what it fetched is cached once it arrives, unless a fetch started later
+        // already is
+        value.then(
+          () => {
+            if ((this.cache.get(region)?.seq ?? 0) < entry.seq) this.cache.set(region, entry)
+          },
+          () => {},
+        )
+      } else {
+        this.cache.set(region, entry)
+        value.catch(() => {
+          if (this.cache.get(region) === entry) this.cache.delete(region)
+        })
+      }
     }
-    return value
+    // a provider may wait on work it shares with other calls: the caller still leaves at once
+    return abortable(value, signal)
   }
 
   /** One group. Accepts loose spellings: "3.1", "GPV3.1", "черга 3.1". */
-  async getSchedule(region: RegionId, group: string, opts: { fresh?: boolean } = {}): Promise<GroupSchedule> {
+  async getSchedule(region: RegionId, group: string, opts: ScheduleOptions = {}): Promise<GroupSchedule> {
     const id = normalizeGroup(group)
     const all = await this.getSchedules(region, opts)
     const days = id ? all.schedules[id] : undefined
@@ -128,16 +155,26 @@ export class OutageClient {
     region: RegionId,
     query: string,
     opts: SearchOptions & { district?: string } = {},
+  ): Promise<City[]> {
+    return this.searchCitiesIn(this.ctx, region, query, opts)
+  }
+
+  private async searchCitiesIn(
+    ctx: ProviderContext,
+    region: RegionId,
+    query: string,
+    opts: SearchOptions & { district?: string },
   ): Promise<City[]> {
     const p = this.provider(region)
     if (!p.searchCities) return []
     const found = await this.rankedSearch(
+      ctx,
       region,
       'settlement',
       query,
       'cities',
       !!p.remoteSearch?.cities,
-      (q) => p.searchCities!(this.ctx, q),
+      (q) => p.searchCities!(ctx, q),
       opts.district ? MAX_CANDIDATES : (opts.limit ?? DEFAULT_LIMIT),
     )
     if (!opts.district) return found
@@ -156,17 +193,27 @@ export class OutageClient {
     region: RegionId,
     query: string,
     opts: SearchOptions & { city?: City } = {},
+  ): Promise<Street[]> {
+    return this.searchStreetsIn(this.ctx, region, query, opts)
+  }
+
+  private async searchStreetsIn(
+    ctx: ProviderContext,
+    region: RegionId,
+    query: string,
+    opts: SearchOptions & { city?: City },
   ): Promise<Street[]> {
     const p = this.addressProvider(region)
     if (p.searchCities && !opts.city)
       throw new OutageError('not-found', `${p.info.name}: pick a city first`, { region })
     return this.rankedSearch(
+      ctx,
       region,
       'street',
       query,
       `streets:${opts.city?.id ?? ''}`,
       !!p.remoteSearch?.streets,
-      (q) => p.searchStreets!(this.ctx, q, opts.city),
+      (q) => p.searchStreets!(ctx, q, opts.city),
       opts.limit ?? DEFAULT_LIMIT,
     )
   }
@@ -187,9 +234,9 @@ export class OutageClient {
   async prefetch(region: RegionId, opts: { city?: City } = {}): Promise<void> {
     const p = this.provider(region)
     if (p.searchCities && !p.remoteSearch?.cities)
-      await this.candidates(region, 'cities', '', false, (q) => p.searchCities!(this.ctx, q))
+      await this.candidates(this.ctx, region, 'cities', '', false, (q) => p.searchCities!(this.ctx, q))
     if (opts.city && p.searchStreets && !p.remoteSearch?.streets)
-      await this.candidates(region, `streets:${opts.city.id}`, '', false, (q) =>
+      await this.candidates(this.ctx, region, `streets:${opts.city.id}`, '', false, (q) =>
         p.searchStreets!(this.ctx, q, opts.city),
       )
   }
@@ -199,24 +246,35 @@ export class OutageClient {
    * or settlement can't be picked with confidence, throws `not-found` listing the suggestions.
    */
   async findGroup(region: RegionId, address: AddressQuery): Promise<GroupMatch> {
+    return this.findGroupIn(this.ctx, region, address)
+  }
+
+  private async findGroupIn(
+    ctx: ProviderContext,
+    region: RegionId,
+    address: AddressQuery,
+  ): Promise<GroupMatch> {
     const direct = this.provider(region)
-    if (direct.lookupAddress) return direct.lookupAddress(this.ctx, address)
+    if (direct.lookupAddress) return direct.lookupAddress(ctx, address)
     const p = this.addressProvider(region)
 
     let city: City | undefined
     if (p.searchCities) {
       if (!address.city)
         throw new OutageError('not-found', `${p.info.name}: specify a city or village`, { region })
-      const cities = await this.searchCities(region, address.city, { limit: 10, district: address.district })
+      const cities = await this.searchCitiesIn(ctx, region, address.city, {
+        limit: 10,
+        district: address.district,
+      })
       city = choose(address.city, cities, 'city', region, (c) =>
         c.district ? `${c.name} (${c.district})` : c.name,
       )
     }
 
-    const streets = await this.searchStreets(region, address.street, { city, limit: 10 })
+    const streets = await this.searchStreetsIn(ctx, region, address.street, { city, limit: 10 })
     const street = choose(address.street, streets, 'street', region, (s) => s.name)
 
-    const houses = await p.searchHouses!(this.ctx, street, address.house)
+    const houses = await p.searchHouses!(ctx, street, address.house)
     const want = normalizeHouse(address.house)
     const house = houses.find((h) => normalizeHouse(h.number) === want)
     if (!house)
@@ -230,7 +288,7 @@ export class OutageClient {
         }`,
         { region },
       )
-    return p.groupOf!(this.ctx, house, street, city)
+    return p.groupOf!(ctx, house, street, city)
   }
 
   /**
@@ -239,6 +297,7 @@ export class OutageClient {
    * query alone finds little, so a typo in one part of the name still lands.
    */
   private async rankedSearch<T extends { id: string; name: string }>(
+    ctx: ProviderContext,
     region: RegionId,
     kind: NameKind,
     query: string,
@@ -248,13 +307,17 @@ export class OutageClient {
     limit: number,
   ): Promise<(T & { score: number })[]> {
     if (!query.trim()) return []
-    let pool = await this.candidates(region, scope, query, remote, fetch)
+    let pool = await this.candidates(ctx, region, scope, query, remote, fetch)
     let ranked = rankByName(query, pool, (t) => t.name, kind)
     // a typo defeats the operator's substring search: retry with fragments of the word
     if (remote && (ranked[0]?.score ?? 0) < 0.9) {
       const extra = await Promise.all(
         searchFragments(query, kind).map((f) =>
-          this.candidates(region, scope, f, true, fetch).catch(() => []),
+          this.candidates(ctx, region, scope, f, true, fetch).catch(() => {
+            // a cancelled lookup stops here; any other failure of a fragment is just no extra hits
+            ctx.signal?.throwIfAborted()
+            return []
+          }),
         ),
       )
       const seen = new Map(pool.map((t) => [t.id, t]))
@@ -267,6 +330,7 @@ export class OutageClient {
 
   /** Candidate lists, cached briefly: whole directories per scope, server results per term. */
   private candidates<T>(
+    ctx: ProviderContext,
     region: RegionId,
     scope: string,
     query: string,
@@ -275,11 +339,19 @@ export class OutageClient {
   ): Promise<T[]> {
     const key = `${region}|${scope}|${remote ? query.trim().toLowerCase() : ''}`
     const hit = this.searchCache.get(key)
-    if (hit && Date.now() - hit.at < Math.max(this.cacheTtlMs, 60_000)) return hit.value as Promise<T[]>
+    if (hit && Date.now() - hit.at < Math.max(this.cacheTtlMs, 60_000))
+      return abortable(hit.value as Promise<T[]>, ctx.signal)
     const value = fetch(query)
-    if (this.searchCache.size > 500) this.searchCache.clear()
-    this.searchCache.set(key, { at: Date.now(), value })
-    value.catch(() => this.searchCache.delete(key))
+    const store = () => {
+      if (this.searchCache.size > 500) this.searchCache.clear()
+      this.searchCache.set(key, { at: Date.now(), value })
+    }
+    // a cancellable lookup isn't shared while it runs, so no other caller inherits its cancellation
+    if (ctx.signal) value.then(store, () => {})
+    else {
+      store()
+      value.catch(() => this.searchCache.delete(key))
+    }
     return value
   }
 
@@ -292,17 +364,25 @@ export class OutageClient {
   async healthCheck(opts: HealthCheckOptions = {}): Promise<HealthReport> {
     const ids = opts.regions ?? [...this.providers.keys()]
     const staleMs = (opts.staleAfterHours ?? 72) * 3600_000
-    const results = await mapLimit(ids, opts.concurrency ?? 6, async (id): Promise<RegionHealth> => {
-      const health = await this.checkRegion(id, staleMs)
-      const p = this.provider(id)
-      if (!opts.address || !p.sampleAddress || !p.info.capabilities.addressSearch) return health
-      try {
-        const m = await this.findGroup(id, p.sampleAddress)
-        return { ...health, address: { ok: true, group: m.group } }
-      } catch (e) {
-        return { ...health, address: { ok: false, message: (e as Error).message } }
-      }
-    })
+    const { signal } = opts
+    const results = await mapLimit(
+      ids,
+      opts.concurrency ?? 6,
+      async (id): Promise<RegionHealth> => {
+        const health = await this.checkRegion(id, staleMs, signal)
+        const p = this.provider(id)
+        if (!opts.address || !p.sampleAddress || !p.info.capabilities.addressSearch) return health
+        signal?.throwIfAborted()
+        try {
+          const m = await abortable(this.findGroupIn(this.context(signal), id, p.sampleAddress), signal)
+          return { ...health, address: { ok: true, group: m.group } }
+        } catch (e) {
+          if (signal?.aborted) throw signal.reason
+          return { ...health, address: { ok: false, message: (e as Error).message } }
+        }
+      },
+      signal,
+    )
     return {
       checkedAt: this.ctx.now().toISOString(),
       ok: results.every((r) => r.status !== 'error' && (r.address?.ok ?? true)),
@@ -310,7 +390,7 @@ export class OutageClient {
     }
   }
 
-  private async checkRegion(region: RegionId, staleMs: number): Promise<RegionHealth> {
+  private async checkRegion(region: RegionId, staleMs: number, signal?: AbortSignal): Promise<RegionHealth> {
     const info = this.provider(region).info
     // e.g. operators that publish the schedule only as an image: nothing to check
     if (!info.capabilities.schedule)
@@ -324,11 +404,12 @@ export class OutageClient {
       }
     const started = performance.now()
     try {
-      const s = await this.getSchedules(region, { fresh: true })
+      const s = await this.getSchedules(region, { fresh: true, signal })
       const latencyMs = Math.round(performance.now() - started)
       const base = { region, latencyMs, groups: s.groups.length, updatedAt: s.updatedAt }
       const hasData = Object.values(s.schedules).some((days) =>
-        days.some((d) => d.intervals.length > 0 || d.status === 'no-outages'),
+        // anything the operator published counts, a day without outages included
+        days.some((d) => d.status !== 'unknown'),
       )
       if (!s.groups.length || !hasData)
         return { ...base, status: 'empty', message: 'No schedule published right now' }
@@ -336,6 +417,7 @@ export class OutageClient {
         return { ...base, status: 'stale', message: `Last updated ${s.updatedAt}` }
       return { ...base, status: 'ok' }
     } catch (e) {
+      if (signal?.aborted) throw signal.reason
       // e.g. a region that publishes only an image the SDK can't read
       if (e instanceof OutageError && e.code === 'unsupported')
         return { region, status: 'empty', latencyMs: 0, groups: 0, updatedAt: null, message: e.message }
@@ -352,6 +434,11 @@ export class OutageClient {
 
   // --- internals ---
 
+  /** Provider context for one call; with a signal, its requests stop when the call is cancelled */
+  private context(signal?: AbortSignal): ProviderContext {
+    return signal ? { ...this.ctx, http: this.ctx.http.withSignal(signal), signal } : this.ctx
+  }
+
   private provider(id: RegionId): Provider {
     const p = this.providers.get(id)
     if (!p) throw new OutageError('unsupported', `Unknown region "${id}"`, { region: id })
@@ -407,6 +494,13 @@ const CONFIDENT = 0.7
 /** …and only when the runner-up is further behind than this */
 const TIE = 0.025
 
+export interface ScheduleOptions {
+  /** Skip the cache and fetch from the operator */
+  fresh?: boolean
+  /** Cancels the call: it rejects with the signal's reason and sends no further requests */
+  signal?: AbortSignal
+}
+
 export interface SearchOptions {
   /** Max results, default 10 */
   limit?: number

package/src/http.ts

@@ -1,6 +1,7 @@
 import { OutageError } from './errors.js'
 import { httpsFetchWithCa } from './https-fetch.js'
 import type { RegionId } from './types.js'
+import { abortable } from './util.js'
 
 export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
 
@@ -41,6 +42,9 @@ const BLOCK_MARKERS = [
   'Attention Required!',
 ]
 
+/** A bot-protection page rather than the operator's content. Challenge pages are small; real pages may embed the same scripts, so size matters. */
+const isChallenge = (body: string) => body.length < 20_000 && BLOCK_MARKERS.some((m) => body.includes(m))
+
 export class Http {
   private readonly fetchImpl: FetchLike
   private readonly customFetch: boolean
@@ -48,6 +52,8 @@ export class Http {
   private readonly timeoutMs: number
   private readonly userAgent: string
   private readonly retries: number
+  /** Set on copies made by `withSignal`: every request through them stops when it aborts */
+  private signal?: AbortSignal
 
   constructor(opts: HttpOptions = {}) {
     this.fetchImpl = opts.fetch ?? ((input, init) => globalThis.fetch(input, init))
@@ -57,6 +63,17 @@ export class Http {
     this.retries = opts.retries ?? 1
   }
 
+  /**
+   * The same client (settings, connections) whose requests all stop when `signal` aborts:
+   * none starts after that, and the one in flight is cancelled. `undefined` gives an unbound copy.
+   */
+  withSignal(signal: AbortSignal | undefined): Http {
+    const copy = Object.create(Http.prototype) as Http
+    Object.assign(copy, this)
+    copy.signal = signal
+    return copy
+  }
+
   async text(url: string, opts: RequestOptions = {}): Promise<string> {
     return (await this.raw(url, opts)).body
   }
@@ -67,11 +84,11 @@ export class Http {
     opts: RequestOptions = {},
   ): Promise<{ body: string; headers: Headers; status: number }> {
     const res = await this.request(url, opts)
+    const signal = this.signal
     const body = opts.encoding
-      ? new TextDecoder(opts.encoding).decode(await res.arrayBuffer())
-      : await res.text()
-    // challenge pages are small; real pages may embed the same scripts, so size matters
-    if (body.length < 20_000 && BLOCK_MARKERS.some((m) => body.includes(m)))
+      ? new TextDecoder(opts.encoding).decode(await abortable(res.arrayBuffer(), signal))
+      : await abortable(res.text(), signal)
+    if (isChallenge(body))
       throw new OutageError('blocked', `Bot protection answered instead of ${host(url)}`, {
         region: opts.region,
         url,
@@ -88,7 +105,8 @@ export class Http {
   /** Binary body with the response headers (e.g. Last-Modified of an image) */
   async file(url: string, opts: RequestOptions = {}): Promise<{ bytes: Uint8Array; headers: Headers }> {
     const res = await this.request(url, opts)
-    return { bytes: new Uint8Array(await res.arrayBuffer()), headers: res.headers }
+    const bytes = await abortable(res.arrayBuffer(), this.signal)
+    return { bytes: new Uint8Array(bytes), headers: res.headers }
   }
 
   async json<T = unknown>(url: string, opts: RequestOptions = {}): Promise<T> {
@@ -112,6 +130,7 @@ export class Http {
   }
 
   private async request(url: string, opts: RequestOptions): Promise<Response> {
+    const signal = this.signal
     const headers: Record<string, string> = {
       'User-Agent': this.userAgent,
       Accept: 'application/json, text/html;q=0.9, */*;q=0.8',
@@ -127,16 +146,23 @@ export class Http {
 
     const fetchImpl = opts.ca && !this.customFetch ? this.fetchWithCa(opts.ca) : this.fetchImpl
     for (let attempt = 0; ; attempt++) {
+      // a cancelled call sends nothing more, retries included
+      signal?.throwIfAborted()
+      const timeout = AbortSignal.timeout(this.timeoutMs)
       let res: Response
       try {
-        res = await fetchImpl(url, {
-          method: opts.method ?? (body ? 'POST' : 'GET'),
-          headers,
-          body,
-          signal: AbortSignal.timeout(this.timeoutMs),
-          redirect: 'follow',
-        })
+        res = await abortable(
+          fetchImpl(url, {
+            method: opts.method ?? (body ? 'POST' : 'GET'),
+            headers,
+            body,
+            signal: signal ? withTimeout(signal, timeout) : timeout,
+            redirect: 'follow',
+          }),
+          signal,
+        )
       } catch (cause) {
+        if (signal?.aborted) throw signal.reason
         if (attempt < this.retries) continue
         const timedOut = (cause as Error)?.name === 'TimeoutError'
         throw new OutageError(
@@ -146,6 +172,17 @@ export class Http {
         )
       }
       if (res.ok || opts.acceptStatus?.includes(res.status)) return res
+      // a bot check often comes as a 503: look before retrying, and never ask it twice
+      const errorBody = await abortable(res.text(), signal).catch(() => {
+        if (signal?.aborted) throw signal.reason
+        return ''
+      })
+      if (isChallenge(errorBody))
+        throw new OutageError('blocked', `Bot protection answered instead of ${host(url)}`, {
+          region: opts.region,
+          url,
+          status: res.status,
+        })
       if (res.status >= 500 && attempt < this.retries) continue
       throw new OutageError(
         res.status === 403 || res.status === 429 ? 'blocked' : 'http',
@@ -156,6 +193,30 @@ export class Http {
   }
 }
 
+/**
+ * Aborts on the caller's signal or the per-request timeout: `AbortSignal.any`, which Node 20 has
+ * only from 20.3. The fallback's listeners go away when either fires, and the timeout always
+ * fires, so a caller's signal shared by many requests doesn't collect them.
+ */
+function withTimeout(caller: AbortSignal, timeout: AbortSignal): AbortSignal {
+  if (typeof AbortSignal.any === 'function') return AbortSignal.any([timeout, caller])
+  const ctrl = new AbortController()
+  if (caller.aborted) ctrl.abort(caller.reason)
+  else if (timeout.aborted) ctrl.abort(timeout.reason)
+  else {
+    const onCaller = () => ctrl.abort(caller.reason)
+    const onTimeout = () => ctrl.abort(timeout.reason)
+    const cleanup = () => {
+      caller.removeEventListener('abort', onCaller)
+      timeout.removeEventListener('abort', onTimeout)
+    }
+    caller.addEventListener('abort', onCaller, { once: true })
+    timeout.addEventListener('abort', onTimeout, { once: true })
+    ctrl.signal.addEventListener('abort', cleanup, { once: true })
+  }
+  return ctrl.signal
+}
+
 function host(url: string) {
   try {
     return new URL(url).host

package/src/index.ts

@@ -1,5 +1,11 @@
 export { OutageClient } from './client.js'
-export type { HealthCheckOptions, HealthReport, OutageClientOptions, SearchOptions } from './client.js'
+export type {
+  HealthCheckOptions,
+  HealthReport,
+  OutageClientOptions,
+  ScheduleOptions,
+  SearchOptions,
+} from './client.js'
 export { OutageError, isOutageError } from './errors.js'
 export { fuzzyScore, rankByName } from './fuzzy.js'
 export type { NameKind } from './fuzzy.js'

package/src/providers/gpv.ts

@@ -63,6 +63,16 @@ export function parseGpvDays(
     for (const [rawGroup, cells] of Object.entries(groups)) {
       const group = normalizeGroup(rawGroup)
       if (!group || !cells || typeof cells !== 'object') continue
+      // a group without cells says nothing about its day: unknown, not "power on all day"
+      const hours = Object.keys(cells).filter((k) => /^\d+$/.test(k))
+      if (!hours.length) {
+        ;(out[group] ??= []).push({ date, status: 'unknown', intervals: [] })
+        continue
+      }
+      // a cell value nobody has seen is reported, not read as "on"
+      const odd = hours.map((k) => String(cells[k]).toLowerCase()).find((v) => v !== 'yes' && !HALF[v])
+      if (odd !== undefined)
+        throw new OutageError('parse', `GPV: unknown cell value "${odd}" in ${rawGroup}`, { region })
       ;(out[group] ??= []).push(makeDay(date, gpvCellsToSlots(cells)))
     }
   }

package/src/providers/image-schedule.ts

@@ -31,10 +31,13 @@ export async function scheduleFromImages(
     let lastError = ''
     let read = false
     for (const img of images) {
+      ctx.signal?.throwIfAborted()
       let cells
       try {
         cells = readScheduleTable(decodePng(await ctx.http.bytes(url(img.path), { region })), layout)
       } catch (e) {
+        // a cancelled call is not an unreadable image
+        ctx.signal?.throwIfAborted()
         if (e instanceof OutageError) throw e
         lastError = `${img.path}: ${(e as Error).message}`
         continue

package/src/providers/ivano-frankivsk.ts

@@ -1,5 +1,5 @@
 import { OutageError } from '../errors.js'
-import { compareGroups, makeDay, normalizeGroup, type MinuteSlot } from '../schedule.js'
+import { compareGroups, makeDay, normalizeGroup, unpublished, type MinuteSlot } from '../schedule.js'
 import { parseClock, toKyivIso } from '../time.js'
 import type { AddressQuery, DaySchedule, GroupId, GroupMatch, RegionInfo, RegionSchedule } from '../types.js'
 import type { Provider, ProviderContext } from './provider.js'
@@ -75,8 +75,11 @@ export function ivanoFrankivskProvider(): Provider {
     sampleAddress: { city: 'Івано-Франківськ', street: 'Галицька', house: '1' },
 
     async getSchedules(ctx) {
-      const responses = await mapLimit(GROUPS, CONCURRENCY, (g) =>
-        ctx.http.json<unknown>(`${API}/schedule-by-queue?queue=${g}`, { region }),
+      const responses = await mapLimit(
+        GROUPS,
+        CONCURRENCY,
+        (g) => ctx.http.json<unknown>(`${API}/schedule-by-queue?queue=${g}`, { region }),
+        ctx.signal,
       )
       return parseQueueSchedules(responses, ctx.now())
     },
@@ -155,7 +158,7 @@ export function parseQueueSchedules(responses: readonly unknown[], now: Date): R
   }
 
   const dates = [...byDate.keys()].sort()
-  if (!dates.length) return { region, groups: [], schedules: {}, updatedAt: null, fetchedAt: toKyivIso(now) }
+  if (!dates.length) return unpublished(region, GROUPS, now)
 
   const groups = [...new Set([...GROUPS, ...dates.flatMap((d) => [...byDate.get(d)!.keys()])])].sort(
     compareGroups,

package/src/providers/khmelnytskyi.ts

@@ -198,8 +198,8 @@ export function textSchedules(
   html: string,
   now: Date,
   from: string,
-): Map<string, Record<string, MinuteSlot[]>> {
-  const out = new Map<string, Record<string, MinuteSlot[]>>()
+): Map<string, Record<string, MinuteSlot[] | null>> {
+  const out = new Map<string, Record<string, MinuteSlot[] | null>>()
   const start = html.indexOf('class="post"')
   if (start === -1) return out
   const end = html.indexOf('Перевірити чергу', start)
@@ -220,11 +220,20 @@ export function textSchedules(
   return out
 }
 
-function mergeText(images: RegionSchedule, text: Map<string, Record<string, MinuteSlot[]>>): RegionSchedule {
+function mergeText(
+  images: RegionSchedule,
+  text: Map<string, Record<string, MinuteSlot[] | null>>,
+): RegionSchedule {
   if (!text.size) return images
   const schedules: Record<string, DaySchedule[]> = { ...images.schedules }
   for (const [date, groups] of text)
-    for (const g of STANDARD_GROUPS) schedules[g] = [...(schedules[g] ?? []), makeDay(date, groups[g] ?? [])]
+    for (const g of STANDARD_GROUPS) {
+      const slots = groups[g]
+      // named without times or a "power on" statement: not known (an unlisted group has none)
+      const day: DaySchedule =
+        slots === null ? { date, status: 'unknown', intervals: [] } : makeDay(date, slots ?? [])
+      schedules[g] = [...(schedules[g] ?? []), day]
+    }
   for (const g of Object.keys(schedules)) schedules[g]!.sort((a, b) => a.date.localeCompare(b.date))
   return { ...images, groups: Object.keys(schedules).sort(compareGroups), schedules }
 }

package/src/providers/kirovohrad.ts

@@ -14,7 +14,7 @@ import type {
   Street,
 } from '../types.js'
 import type { Provider, ProviderContext } from './provider.js'
-import { cookieHeader, mapLimit } from '../util.js'
+import { SharedTask, cookieHeader, mapLimit } from '../util.js'
 
 /**
  * Kirovohradoblenergo (kiroe.com.ua). The /electricity-blackout page hands out a PHP session
@@ -71,7 +71,7 @@ export interface ApiHouse {
 
 export function kirovohradProvider(): Provider {
   const region = INFO.id
-  let current: Promise<Session> | null = null
+  let current: SharedTask<Session> | null = null
   let currentAt = 0
   let cities: Promise<City[]> | null = null
   // house id → its number and groups, filled by searchHouses so groupOf needs no extra request
@@ -95,15 +95,19 @@ export function kirovohradProvider(): Provider {
   }
 
   const session = (ctx: ProviderContext, renew = false): Promise<Session> => {
-    if (renew || !current || Date.now() - currentAt > SESSION_TTL_MS) {
+    if (renew || !current || current.aborted || Date.now() - currentAt > SESSION_TTL_MS) {
       currentAt = Date.now()
-      const p = bootstrap(ctx)
-      current = p
-      p.catch(() => {
-        if (current === p) current = null
+      // shared by concurrent calls: one caller cancelling doesn't fail the others, and it is
+      // cancelled only when every caller waiting for it has given up
+      const task = new SharedTask((signal) =>
+        bootstrap({ ...ctx, http: ctx.http.withSignal(signal), signal }),
+      )
+      current = task
+      task.promise.catch(() => {
+        if (current === task) current = null
       })
     }
-    return current
+    return current.join(ctx.signal)
   }
 
   const post = async (ctx: ProviderContext, s: Session, path: string): Promise<unknown> => {

package/src/providers/lviv.ts

@@ -1,5 +1,5 @@
 import { OutageError } from '../errors.js'
-import { compareGroups, makeDay, normalizeGroup } from '../schedule.js'
+import { compareGroups, makeDay, normalizeGroup, unpublished } from '../schedule.js'
 import { toKyivIso } from '../time.js'
 import type { DaySchedule, GroupId, RegionInfo, RegionSchedule } from '../types.js'
 import { parseUaDateTime } from './gpv.js'
@@ -125,7 +125,7 @@ export function parseLvivMenu(data: unknown, now: Date): RegionSchedule {
       const groups: Record<GroupId, DaySchedule> = {}
       for (const [raw, slots] of Object.entries(parsed)) {
         const g = normalizeGroup(raw)
-        if (g) groups[g] = makeDay(day, slots)
+        if (g) groups[g] = slots ? makeDay(day, slots) : { date: day, status: 'unknown', intervals: [] }
       }
       if (!Object.keys(groups).length)
         throw new OutageError('parse', `Lviv ${item.name}: schedule text without groups (format changed?)`, {
@@ -150,6 +150,8 @@ export function parseLvivMenu(data: unknown, now: Date): RegionSchedule {
   }
 
   const dates = [...days.keys()].sort()
+  // every slot empty: nothing published; the twelve groups stay listed as unknown
+  if (!dates.length) return unpublished(region, STANDARD_GROUPS, now)
   const groups = [...new Set(dates.flatMap((d) => Object.keys(days.get(d)!.groups)))].sort(compareGroups)
   const schedules: Record<GroupId, DaySchedule[]> = {}
   for (const g of groups)

package/src/providers/mykolaiv.ts

@@ -1,5 +1,5 @@
 import { OutageError } from '../errors.js'
-import { compareGroups, makeDay, type MinuteSlot } from '../schedule.js'
+import { compareGroups, makeDay, unpublished, type MinuteSlot } from '../schedule.js'
 import { kyivDate, toKyivIso } from '../time.js'
 import type { City, DaySchedule, GroupMatch, RegionInfo, RegionSchedule } from '../types.js'
 import type { Provider, ProviderContext } from './provider.js'
@@ -156,12 +156,14 @@ export function parseActive(slots: Slot[], queues: Queue[], active: ActiveDay[],
   const groups = [...nameOf.values()].sort(compareGroups)
   const schedules: Record<string, DaySchedule[]> = {}
   const dates = [...byDate.keys()].sort()
+  // no active day: nothing published, which is not "no outages"
+  if (!dates.length) return unpublished(region, groups, now)
   for (const g of groups) schedules[g] = dates.map((d) => makeDay(d, byDate.get(d)!.get(g) ?? []))
 
   return {
     region,
-    groups: dates.length ? groups : [],
-    schedules: dates.length ? schedules : {},
+    groups,
+    schedules,
     updatedAt: updated ? toKyivIso(new Date(updated)) : null,
     fetchedAt: toKyivIso(now),
   }

package/src/providers/posts.ts

@@ -1,4 +1,4 @@
-import { compareGroups, makeDay } from '../schedule.js'
+import { compareGroups, makeDay, unpublished } from '../schedule.js'
 import { addDays, kyivDate, toKyivIso } from '../time.js'
 import type { DaySchedule, RegionId, RegionSchedule } from '../types.js'
 import { findUaDate, parseGroupLines } from './ua-text.js'
@@ -53,7 +53,9 @@ export function postsToSchedule(
   }
 
   const dates = [...byDate.keys()].sort()
-  const groupSet = new Set<string>(dates.length ? (opts.groups ?? []) : [])
+  // no post with a schedule: the region's groups (when known) stay listed, unknown for today
+  if (!dates.length) return unpublished(region, opts.groups ?? [], now)
+  const groupSet = new Set<string>(opts.groups ?? [])
   for (const d of byDate.values()) for (const g of Object.keys(d.groups)) groupSet.add(g)
   const groups = [...groupSet].sort(compareGroups)
 
@@ -62,6 +64,8 @@ export function postsToSchedule(
     schedules[g] = dates.map((d) => {
       const slots = byDate.get(d)!.groups[g]
       if (slots) return makeDay(d, slots)
+      // named in the post without times or a "power on" statement: not known
+      if (slots === null) return { date: d, status: 'unknown' as const, intervals: [] }
       // a group missing from that day's post: no outages if the operator lists only the
       // groups that have them, otherwise we just don't know
       return opts.omitted === 'none' ? makeDay(d, []) : { date: d, status: 'unknown' as const, intervals: [] }

package/src/providers/provider.ts

@@ -2,8 +2,16 @@ import type { Http } from '../http.js'
 import type { AddressQuery, City, GroupMatch, House, RegionInfo, RegionSchedule, Street } from '../types.js'
 
 export interface ProviderContext {
+  /** Already bound to `signal`: every request through it stops when the call is cancelled */
   http: Http
   now: () => Date
+  /**
+   * The caller's cancellation, if any. Requests stop by themselves; pass it to `mapLimit` and
+   * check it in long loops. Work shared between calls (a session several calls wait for) should
+   * run on `http.withSignal(undefined)` and be awaited with `abortable(…, signal)`, so one
+   * caller giving up doesn't fail the others.
+   */
+  signal?: AbortSignal
 }
 
 /**

package/src/providers/sumy.ts

@@ -230,13 +230,12 @@ export function parseSumySchedules(res: { data?: ScheduleEntry[] }, now: Date):
     if (at && (!updated || Date.parse(at) > Date.parse(updated))) updated = at
   }
 
-  // every group "no data": nothing is published
-  const known = Object.keys(schedules).filter((g) => schedules[g]![0]!.status !== 'unknown')
-  const groups = known.length ? Object.keys(schedules).sort(compareGroups) : []
+  // a group marked "no data" stays listed with an `unknown` day, even when every group is: that
+  // means nothing is published, which must not read as "no outages"
   return {
     region,
-    groups,
-    schedules: groups.length ? schedules : {},
+    groups: Object.keys(schedules).sort(compareGroups),
+    schedules,
     updatedAt: updated,
     fetchedAt: toKyivIso(now),
   }

package/src/providers/ternopil.ts

@@ -1,9 +1,10 @@
 import { OutageError } from '../errors.js'
-import { cellsToIntervals } from '../schedule.js'
+import { cellsToIntervals, unpublished } from '../schedule.js'
 import { addDays, kyivDate, toKyivIso } from '../time.js'
 import type { DaySchedule, GroupId, IntervalKind, RegionInfo, RegionSchedule } from '../types.js'
 import { STANDARD_GROUPS, parseCherg, parsePowerOnTime, powerOnAddressSearch } from './poweron.js'
 import type { Provider, ProviderContext } from './provider.js'
+import { mapLimit } from '../util.js'
 
 /**
  * Ternopiloblenergo (poweron.toe.com.ua), a PowerOn platform backend.
@@ -110,7 +111,12 @@ export function ternopilProvider(): Provider {
     async getSchedules(ctx) {
       const groups = Object.keys(REPRESENTATIVES)
       // a few at a time: twelve requests per refresh is already more than the site makes
-      const results = await mapLimit(groups, 3, (g) => fetchWithRetry(ctx, g, ['unknown-address']))
+      const results = await mapLimit(
+        groups,
+        3,
+        (g) => fetchWithRetry(ctx, g, ['unknown-address']),
+        ctx.signal,
+      )
       const anyDays = results.some((r) => r.kind === 'days')
       if (anyDays)
         for (const [i, r] of results.entries())
@@ -212,7 +218,8 @@ export function buildSchedule(byGroup: Record<GroupId, GroupGraph>, now: Date):
     (r): r is Extract<GroupGraph, { kind: 'days' }> => r.kind === 'days',
   )
   const fetchedAt = toKyivIso(now)
-  if (!withDays.length) return { region, groups: [], schedules: {}, updatedAt: null, fetchedAt }
+  // nothing published for any group: not "no outages", just nothing known yet
+  if (!withDays.length) return unpublished(region, Object.keys(byGroup), now)
 
   const dates = [...new Set(withDays.flatMap((r) => r.days.map((d) => d.date)))].sort()
   const groups = STANDARD_GROUPS.filter((g) => g in byGroup)
@@ -260,16 +267,3 @@ function base64Utf8(s: string): string {
   for (const b of new TextEncoder().encode(s)) bin += String.fromCharCode(b)
   return btoa(bin)
 }
-
-async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (t: T) => Promise<R>): Promise<R[]> {
-  const out: R[] = new Array(items.length)
-  let next = 0
-  const worker = async () => {
-    while (next < items.length) {
-      const i = next++
-      out[i] = await fn(items[i]!)
-    }
-  }
-  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker))
-  return out
-}

package/src/providers/ua-text.ts

@@ -79,13 +79,22 @@ export function findTimeRanges(text: string): [number, number][] {
   return out
 }
 
+/** A group line without times that says the power stays on ("Група 2.1. Електроенергія є.") */
+const POWER_ON =
+  /електроенергі[яї]\s+є|світло\s+є|без\s+відключень|відключен\S*\s+не\s+(?:передбачен|планує|застосов)/i
+
 /**
  * Lines like "1.1 00:00-03:00; 08:00-13:30", "1.1: 12:00 – 17:00", "Група 1.1. … з 08:00 до 12:00"
- * → group → off slots. A group mentioned with no times (e.g. "Електроенергія є") gets `[]`.
- * Lines that name several groups ("Групи 1.1, 1.2: …") apply the times to each.
+ * → group → off slots. A group mentioned with no times gets `[]` only when the line says the
+ * power stays on ("Електроенергія є"); otherwise ("1.1: графік уточнюється") it gets `null`:
+ * named, but its schedule is not known. Lines that name several groups ("Групи 1.1, 1.2: …")
+ * apply the times to each.
  */
-export function parseGroupLines(text: string, kind: 'off' | 'maybe' = 'off'): Record<string, MinuteSlot[]> {
-  const out: Record<string, MinuteSlot[]> = {}
+export function parseGroupLines(
+  text: string,
+  kind: 'off' | 'maybe' = 'off',
+): Record<string, MinuteSlot[] | null> {
+  const out: Record<string, MinuteSlot[] | null> = {}
   for (const rawLine of text.split(/\n|<br\s*\/?>|<\/p>|<\/li>|<\/div>/i)) {
     const line = rawLine
       .replace(/<[^>]+>/g, ' ')
@@ -101,7 +110,12 @@ export function parseGroupLines(text: string, kind: 'off' | 'maybe' = 'off'): Re
       .filter((g): g is string => !!g)
     if (!groups.length) continue
     const ranges = firstTime === -1 ? [] : findTimeRanges(line.slice(firstTime))
+    const known = ranges.length > 0 || POWER_ON.test(line)
     for (const g of groups) {
+      if (!known) {
+        if (!(g in out)) out[g] = null
+        continue
+      }
       const list = (out[g] ??= [])
       for (const [start, end] of ranges) list.push({ start, end, kind })
     }

package/src/providers/uz.ts

@@ -1,6 +1,6 @@
 import { OutageError } from '../errors.js'
 import { STANDARD_GROUPS } from '../image/table.js'
-import { makeDay, type MinuteSlot } from '../schedule.js'
+import { makeDay, unpublished, type MinuteSlot } from '../schedule.js'
 import { toKyivIso } from '../time.js'
 import type { DaySchedule, RegionId, RegionInfo, RegionSchedule } from '../types.js'
 import type { Provider } from './provider.js'
@@ -101,8 +101,9 @@ export function parseUzPage(
   }
 }
 
+/** A page without a table publishes nothing; that is not "no outages" */
 function empty(region: RegionId, now: Date): RegionSchedule {
-  return { region, groups: [], schedules: {}, updatedAt: null, fetchedAt: toKyivIso(now) }
+  return unpublished(region, STANDARD_GROUPS, now)
 }
 
 const text = (s: string) =>

package/src/providers/zakarpattia.ts

@@ -1,15 +1,21 @@
 import { OutageError } from '../errors.js'
-import { toKyivIso } from '../time.js'
 import type { GroupId, RegionInfo } from '../types.js'
-import { hydraList, parseCherg, powerOnAddressSearch, type PowerOnBuilding } from './poweron.js'
+import { unpublished } from '../schedule.js'
+import {
+  STANDARD_GROUPS,
+  hydraList,
+  parseCherg,
+  powerOnAddressSearch,
+  type PowerOnBuilding,
+} from './poweron.js'
 import type { Provider } from './provider.js'
 
 /**
  * Zakarpattiaoblenergo (outage.zakarpat.energy), a PowerOn platform backend.
  *
  * The schedule itself is published only as a picture (`/options?option_key=pw_gpv_image_today`
- * points to a PNG). While no picture is published, `getSchedules` returns no groups (no
- * outages announced); once one is, it throws `unsupported` with its address, since no sample of
+ * points to a PNG). While no picture is published, `getSchedules` lists the twelve groups with
+ * today `unknown`: nothing published, which is not "no outages". Once one is, it throws `unsupported` with its address, since no sample of
  * that picture exists yet to build a reader from. The address lookup works: `pw_address_queues`
  * returns, per street and group, a comma-separated list of houses.
  */
@@ -57,7 +63,8 @@ export function zakarpattiaProvider(): Provider {
           `Zakarpattia: the schedule is published only as an image (${new URL(published, IMAGE_HOST).href}); use findGroup for the group of an address`,
           { region },
         )
-      return { region, groups: [], schedules: {}, updatedAt: null, fetchedAt: toKyivIso(ctx.now()) }
+      // nothing published: its twelve groups (1.1–6.2, one PDF each on the site) are unknown
+      return unpublished(region, STANDARD_GROUPS, ctx.now())
     },
 
     ...powerOnAddressSearch({

package/src/schedule.ts

@@ -1,5 +1,13 @@
 import { kyivDate, kyivInstant, toKyivIso } from './time.js'
-import type { DaySchedule, DayStatus, GroupId, Interval, IntervalKind } from './types.js'
+import type {
+  DaySchedule,
+  DayStatus,
+  GroupId,
+  Interval,
+  IntervalKind,
+  RegionId,
+  RegionSchedule,
+} from './types.js'
 
 /** A span inside one day, in minutes from Kyiv midnight (end may be 1440). */
 export interface MinuteSlot {
@@ -58,6 +66,24 @@ export function makeDay(day: string, slots: readonly MinuteSlot[], status?: DayS
   return { date: day, status: status ?? 'scheduled', intervals }
 }
 
+/**
+ * A region whose operator publishes nothing right now: each of its groups gets today as
+ * `unknown`. Never `groups: []` when the groups are known, and never `no-outages`: nothing
+ * published is not the same as "no outages announced".
+ */
+export function unpublished(
+  region: RegionId,
+  groups: readonly GroupId[],
+  now: Date,
+  updatedAt: string | null = null,
+): RegionSchedule {
+  const today = kyivDate(now)
+  const sorted = [...new Set(groups)].sort(compareGroups)
+  const schedules: Record<GroupId, DaySchedule[]> = {}
+  for (const g of sorted) schedules[g] = [{ date: today, status: 'unknown', intervals: [] }]
+  return { region, groups: sorted, schedules, updatedAt, fetchedAt: toKyivIso(now) }
+}
+
 /**
  * Normalizes how operators name groups: "GPV1.1", "1.1", "Черга 1.1", "1 черга 2 підчерга",
  * "Група 3.2", "4" → "1.1", "1.1", "1.1", "1.2", "3.2", "4". Returns null if there's no number.

package/src/types.ts

@@ -114,9 +114,14 @@ export interface GroupSchedule {
   fetchedAt: string
 }
 
+/**
+ * Silence is never "no outages": only `no-outages` days, or `scheduled` days without intervals,
+ * mean that. When the operator publishes nothing, its groups are listed with `unknown` days, or,
+ * when the SDK can't tell which groups it has, `groups` is empty. Both mean "not published".
+ */
 export interface RegionSchedule {
   region: RegionId
-  /** Every group the operator publishes, sorted */
+  /** Every group the operator publishes, sorted. Empty: nothing published and groups unknown, not "no outages" */
   groups: GroupId[]
   /** group → days */
   schedules: Record<GroupId, DaySchedule[]>

package/src/util.ts

@@ -1,17 +1,32 @@
-/** Runs `fn` over `items` with at most `limit` in flight; results keep input order. */
+/**
+ * Runs `fn` over `items` with at most `limit` in flight; results keep input order.
+ *
+ * Fails fast: after the first rejection (or once `signal` aborts) no further items are started,
+ * so a site that just refused one request doesn't get the rest of the batch. Calls already in
+ * flight are not interrupted here; pass them the same signal for that.
+ */
 export async function mapLimit<T, R>(
   items: readonly T[],
   limit: number,
   fn: (item: T) => Promise<R>,
+  signal?: AbortSignal,
 ): Promise<R[]> {
   const out: R[] = new Array(items.length)
   let next = 0
+  let failed = false
   const worker = async () => {
-    while (next < items.length) {
+    while (!failed && next < items.length) {
+      signal?.throwIfAborted()
       const i = next++
-      out[i] = await fn(items[i]!)
+      try {
+        out[i] = await fn(items[i]!)
+      } catch (e) {
+        failed = true
+        throw e
+      }
     }
   }
+  signal?.throwIfAborted()
   await Promise.all(Array.from({ length: Math.min(Math.max(1, limit), items.length) }, worker))
   return out
 }
@@ -21,3 +36,67 @@ export function cookieHeader(headers: Headers): string {
   const list = typeof headers.getSetCookie === 'function' ? headers.getSetCookie() : []
   return list.map((c) => c.split(';')[0]).join('; ')
 }
+
+/** Settles like `promise`, or rejects with the signal's reason as soon as it aborts. */
+export function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise
+  if (signal.aborted) {
+    // nobody waits for it any more; a later rejection must not surface as unhandled
+    promise.catch(() => {})
+    return Promise.reject(signal.reason)
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+    signal.addEventListener('abort', onAbort, { once: true })
+    promise.then(
+      (v) => {
+        signal.removeEventListener('abort', onAbort)
+        resolve(v)
+      },
+      (e) => {
+        signal.removeEventListener('abort', onAbort)
+        reject(e)
+      },
+    )
+  })
+}
+
+/**
+ * Work several calls wait on (a session, a directory). It runs on its own signal, which aborts
+ * only when every caller that joined with a signal has given up; a caller without a signal keeps
+ * it running. One caller cancelling never fails the others.
+ */
+export class SharedTask<T> {
+  private readonly ctrl = new AbortController()
+  private waiters = 0
+  private pinned = false
+  private settled = false
+  readonly promise: Promise<T>
+
+  constructor(run: (signal: AbortSignal) => Promise<T>) {
+    this.promise = run(this.ctrl.signal)
+    this.promise.then(
+      () => (this.settled = true),
+      () => (this.settled = true),
+    )
+  }
+
+  /** Abandoned by all its callers: start a new one instead of joining */
+  get aborted(): boolean {
+    return this.ctrl.signal.aborted
+  }
+
+  join(signal?: AbortSignal): Promise<T> {
+    if (!signal) {
+      this.pinned = true
+      return this.promise
+    }
+    this.waiters++
+    // before the task settles a caller can only leave by aborting; after, aborting is moot
+    return abortable(this.promise, signal).catch((e) => {
+      if (signal.aborted && --this.waiters === 0 && !this.pinned && !this.settled)
+        this.ctrl.abort(signal.reason)
+      throw e
+    })
+  }
+}