@skipruntime/helpers 0.0.12 → 0.0.13

package/dist/src/external.d.ts

@@ -1,46 +1,4 @@
 import type { Entry, ExternalService, Json } from "@skipruntime/core";
-/**
- * Interface required by `GenericExternalService` for external resources.
- */
-export interface ExternalResource {
-    open(instance: string, params: Json, callbacks: {
-        update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
-        error: (error: Json) => void;
-        loading: () => void;
-    }): void;
-    close(instance: string): void;
-}
-/**
- * A generic external service providing external resources.
- *
- * `GenericExternalService` provides an implementation of `ExternalService` for external resources by lifting the `open` and `close` operations from `ExternalResource` to the `subscribe` and `unsubscribe` operations required by `ExternalService`.
- */
-export declare class GenericExternalService implements ExternalService {
-    private readonly resources;
-    private readonly instances;
-    /**
-     * @param resources - Association of resource names to `ExternalResource`s.
-     */
-    constructor(resources: {
-        [name: string]: ExternalResource;
-    });
-    subscribe(instance: string, resourceName: string, params: Json, callbacks: {
-        update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
-        error: (error: Json) => void;
-        loading: () => void;
-    }): void;
-    unsubscribe(instance: string): void;
-    shutdown(): Promise<void>;
-}
-export declare class TimerResource implements ExternalResource {
-    private readonly intervals;
-    open(instance: string, params: Json, callbacks: {
-        update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
-        error: (error: Json) => void;
-        loading: () => void;
-    }): void;
-    close(instance: string): void;
-}
 /**
  * Encode params for external resource request.
  *
@@ -51,45 +9,62 @@ export declare class TimerResource implements ExternalResource {
  */
 export declare function defaultParamEncoder(params: Json): string;
 /**
- * An external resource that is refreshed at some polling interval.
+ * Description of an external HTTP endpoint and how to poll it.
+ *
+ * The URL of the external resource is formed by appending the given base `url` and the result of `encodeParams(params)` where `params` are the parameters provided to [`Context#useExternalResource`](api/core/interfaces/Context#useexternalresource)
  *
- * @typeParam S - Type of data received from external resource.
- * @typeParam K - Type of keys.
- * @typeParam V - Type of values.
  */
-export declare class Polled<S extends Json, K extends Json, V extends Json> implements ExternalResource {
-    private readonly url;
-    private readonly duration;
-    private readonly conv;
-    private readonly encodeParams;
-    private readonly options?;
-    private readonly intervals;
+export interface PolledHTTPResource {
     /**
-     * Construct a `Polled` external resource.
-     *
-     * The URL of the external resource is formed by appending the given base `url` and the result of `encodeParams(params)` where `params` are the parameters provided when instantiating the resource.
-     *
-     * Note that the result of `encodeParams` contains the `?` separator, but it need not be at the beginning of the returned string, so some parameters can be used in part of the URL preceding the `?`.
+     * Base URL of resource to poll.
+     */
+    url: string;
+    /**
+     * The interval of time to wait before refreshing the data, given in milliseconds
+     */
+    interval: number;
+    /**
+     * Function to convert data received from external resource to `key`-`value` entries.
+     */
+    conv: (data: Json) => Entry<Json, Json>[];
+    /**
+     * Function to use to encode params of type `Json` for external resource request.
      *
-     * @param url - HTTP endpoint of external resource to poll.
-     * @param duration - Refresh interval, in milliseconds.
-     * @param conv - Function to convert data of type `S` received from external resource to `key`-`value` entries.
-     * @param encodeParams - Function to use to encode params of type `Json` for external resource request.
-     * @param options - Optional parameters.
-     * @param options.headers - Additional headers to add to request.
-     * @param options.timeout - Timeout for request, in milliseconds. Defaults to 1000ms.
+     * Note that the result of `encodeParams` may contain a `?` separator, but it need not be at the beginning of the returned string, so some parameters can be used in part of the URL preceding the `?`.
      */
-    constructor(url: string, duration: number, conv: (data: S) => Entry<K, V>[], encodeParams?: (params: Json) => string, options?: {
+    encodeParams?: (params: Json) => string;
+    /**
+     * Optional parameters: additional `headers` to add to request, and `timeout` for request, in milliseconds. (default 1000ms)
+     */
+    options?: {
         headers?: {
             [header: string]: string;
         };
         timeout?: number;
-    } | undefined);
-    open(instance: string, params: Json, callbacks: {
+    };
+}
+/**
+ * An external HTTP service that is kept up-to-date by polling.
+ *
+ * A `PolledExternalService` may be composed of one or more [`PolledHTTPResource`](api/helpers/interfaces/PolledHTTPResource)s, each of which describes a single endpoint and how to poll it.
+ */
+export declare class PolledExternalService implements ExternalService {
+    private readonly resources;
+    private readonly intervals;
+    /**
+     * Construct a polled external service.
+     *
+     * @param resources - Specification(s) of external resource(s) to poll
+     */
+    constructor(resources: {
+        [resource: string]: PolledHTTPResource;
+    });
+    subscribe(instance: string, resourceName: string, params: Json, callbacks: {
         update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
         error: (error: Json) => void;
         loading: () => void;
     }): void;
-    close(instance: string): void;
+    unsubscribe(instance: string): void;
+    shutdown(): Promise<void>;
 }
 //# sourceMappingURL=external.d.ts.map

package/dist/src/external.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"external.d.ts","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAMtE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,IAAI,GAAG,MAAM,CASxD;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;IAC1C;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,KAAK,MAAM,CAAC;IACxC;;OAEG;IACH,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,eAAe;IASzD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAR5B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IAExD;;;;OAIG;gBAEgB,SAAS,EAAE;QAC1B,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAAC;KACxC;IAGH,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,IAAI,EACZ,SAAS,EAAE;QACT,MAAM,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;QAChE,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,KAAK,IAAI,CAAC;QAC7B,OAAO,EAAE,MAAM,IAAI,CAAC;KACrB;IAwBH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQnC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAO1B"}

package/dist/src/external.js

@@ -1,70 +1,5 @@
 import { SkipUnknownResourceError } from "@skipruntime/core";
 import { fetchJSON } from "./rest.js";
-/**
- * A generic external service providing external resources.
- *
- * `GenericExternalService` provides an implementation of `ExternalService` for external resources by lifting the `open` and `close` operations from `ExternalResource` to the `subscribe` and `unsubscribe` operations required by `ExternalService`.
- */
-export class GenericExternalService {
-    /**
-     * @param resources - Association of resource names to `ExternalResource`s.
-     */
-    constructor(resources) {
-        this.resources = resources;
-        this.instances = new Map();
-    }
-    subscribe(instance, resourceName, params, callbacks) {
-        const resource = this.resources[resourceName];
-        if (!resource) {
-            throw new SkipUnknownResourceError(`Unknown resource named '${resourceName}'`);
-        }
-        this.instances.set(instance, resource);
-        resource.open(instance, params, callbacks);
-    }
-    unsubscribe(instance) {
-        const resource = this.instances.get(instance);
-        if (resource) {
-            resource.close(instance);
-            this.instances.delete(instance);
-        }
-    }
-    shutdown() {
-        return Promise.resolve();
-    }
-}
-export class TimerResource {
-    constructor() {
-        this.intervals = new Map();
-    }
-    open(instance, params, callbacks) {
-        const time = new Date().getTime();
-        const values = [];
-        for (const name of Object.keys(params)) {
-            values.push([name, [time]]);
-        }
-        callbacks.update(values, true);
-        const intervals = {};
-        for (const [name, duration] of Object.entries(params)) {
-            const ms = Number(duration);
-            if (ms > 0) {
-                intervals[name] = setInterval(() => {
-                    const newvalue = [name, [new Date().getTime()]];
-                    callbacks.update([newvalue], true);
-                }, ms);
-            }
-        }
-        this.intervals.set(instance, intervals);
-    }
-    close(instance) {
-        const intervals = this.intervals.get(instance);
-        if (intervals != null) {
-            for (const interval of Object.values(intervals)) {
-                clearInterval(interval);
-            }
-            this.intervals.delete(instance);
-        }
-    }
-}
 /**
  * Encode params for external resource request.
  *
@@ -88,43 +23,30 @@ export function defaultParamEncoder(params) {
         return `?params=${JSON.stringify(params)}`;
 }
 /**
- * An external resource that is refreshed at some polling interval.
+ * An external HTTP service that is kept up-to-date by polling.
  *
- * @typeParam S - Type of data received from external resource.
- * @typeParam K - Type of keys.
- * @typeParam V - Type of values.
+ * A `PolledExternalService` may be composed of one or more [`PolledHTTPResource`](api/helpers/interfaces/PolledHTTPResource)s, each of which describes a single endpoint and how to poll it.
  */
-export class Polled {
+export class PolledExternalService {
     /**
-     * Construct a `Polled` external resource.
-     *
-     * The URL of the external resource is formed by appending the given base `url` and the result of `encodeParams(params)` where `params` are the parameters provided when instantiating the resource.
-     *
-     * Note that the result of `encodeParams` contains the `?` separator, but it need not be at the beginning of the returned string, so some parameters can be used in part of the URL preceding the `?`.
+     * Construct a polled external service.
      *
-     * @param url - HTTP endpoint of external resource to poll.
-     * @param duration - Refresh interval, in milliseconds.
-     * @param conv - Function to convert data of type `S` received from external resource to `key`-`value` entries.
-     * @param encodeParams - Function to use to encode params of type `Json` for external resource request.
-     * @param options - Optional parameters.
-     * @param options.headers - Additional headers to add to request.
-     * @param options.timeout - Timeout for request, in milliseconds. Defaults to 1000ms.
+     * @param resources - Specification(s) of external resource(s) to poll
      */
-    constructor(url, duration, conv, encodeParams = defaultParamEncoder, options) {
-        this.url = url;
-        this.duration = duration;
-        this.conv = conv;
-        this.encodeParams = encodeParams;
-        this.options = options;
+    constructor(resources) {
+        this.resources = resources;
         this.intervals = new Map();
     }
-    open(instance, params, callbacks) {
-        const url = `${this.url}${this.encodeParams(params)}`;
+    subscribe(instance, resourceName, params, callbacks) {
+        const resource = this.resources[resourceName];
+        if (!resource)
+            throw new SkipUnknownResourceError(`Unknown resource named '${resourceName}'`);
+        const url = `${resource.url}${(resource.encodeParams ?? defaultParamEncoder)(params)}`;
         const call = () => {
             callbacks.loading();
-            fetchJSON(url, "GET", this.options)
+            fetchJSON(url, "GET", resource.options ?? {})
                 .then((r) => {
-                callbacks.update(this.conv(r[0]), true);
+                callbacks.update(resource.conv(r[0] ?? []), true);
             })
                 .catch((e) => {
                 callbacks.error(e instanceof Error ? e.message : JSON.stringify(e));
@@ -132,14 +54,21 @@ export class Polled {
             });
         };
         call();
-        this.intervals.set(instance, setInterval(call, this.duration));
+        this.intervals.set(instance, setInterval(call, resource.interval));
     }
-    close(instance) {
+    unsubscribe(instance) {
         const interval = this.intervals.get(instance);
         if (interval) {
             clearInterval(interval);
             this.intervals.delete(instance);
         }
     }
+    shutdown() {
+        for (const [instance, interval] of Object.entries(this.intervals)) {
+            clearInterval(interval);
+            this.intervals.delete(instance);
+        }
+        return Promise.resolve();
+    }
 }
 //# sourceMappingURL=external.js.map

package/dist/src/external.js.map

@@ -1 +1 @@
-{"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"external.js","sourceRoot":"","sources":["../../src/external.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -3,7 +3,7 @@
  *
  * @packageDocumentation
  */
-export { defaultParamEncoder, type ExternalResource, GenericExternalService, Polled, TimerResource, } from "./external.js";
+export { defaultParamEncoder, PolledExternalService } from "./external.js";
 export { SkipExternalService } from "./remote.js";
 export { SkipServiceBroker, fetchJSON, type Entrypoint } from "./rest.js";
 export { Count, Max, Min, Sum } from "./utils.js";

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,sBAAsB,EACtB,MAAM,EACN,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/index.js

@@ -3,7 +3,7 @@
  *
  * @packageDocumentation
  */
-export { defaultParamEncoder, GenericExternalService, Polled, TimerResource, } from "./external.js";
+export { defaultParamEncoder, PolledExternalService } from "./external.js";
 export { SkipExternalService } from "./remote.js";
 export { SkipServiceBroker, fetchJSON } from "./rest.js";
 export { Count, Max, Min, Sum } from "./utils.js";

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,mBAAmB,EAEnB,sBAAsB,EACtB,MAAM,EACN,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAmB,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAmB,MAAM,WAAW,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skipruntime/helpers",
-  "version": "0.0.12",
+  "version": "0.0.13",
   "type": "module",
   "exports": {
     ".": "./dist/src/index.js"
@@ -19,7 +19,7 @@
   "dependencies": {
     "eventsource": "^2.0.2",
     "express": "^4.21.1",
-    "@skipruntime/core": "0.0.12"
+    "@skipruntime/core": "0.0.13"
   },
   "devDependencies": {
     "@types/eventsource": "^1.1.15"

package/src/external.ts

@@ -2,117 +2,7 @@ import type { Entry, ExternalService, Json } from "@skipruntime/core";
 import { SkipUnknownResourceError } from "@skipruntime/core";
 import { fetchJSON } from "./rest.js";
 
-/**
- * Interface required by `GenericExternalService` for external resources.
- */
-export interface ExternalResource {
-  open(
-    instance: string,
-    params: Json,
-    callbacks: {
-      update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
-      error: (error: Json) => void;
-      loading: () => void;
-    },
-  ): void;
-
-  close(instance: string): void;
-}
-
-/**
- * A generic external service providing external resources.
- *
- * `GenericExternalService` provides an implementation of `ExternalService` for external resources by lifting the `open` and `close` operations from `ExternalResource` to the `subscribe` and `unsubscribe` operations required by `ExternalService`.
- */
-export class GenericExternalService implements ExternalService {
-  private readonly instances = new Map<string, ExternalResource>();
-
-  /**
-   * @param resources - Association of resource names to `ExternalResource`s.
-   */
-  constructor(
-    private readonly resources: { [name: string]: ExternalResource },
-  ) {}
-
-  subscribe(
-    instance: string,
-    resourceName: string,
-    params: Json,
-    callbacks: {
-      update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
-      error: (error: Json) => void;
-      loading: () => void;
-    },
-  ) {
-    const resource = this.resources[resourceName] as
-      | ExternalResource
-      | undefined;
-    if (!resource) {
-      throw new SkipUnknownResourceError(
-        `Unknown resource named '${resourceName}'`,
-      );
-    }
-    this.instances.set(instance, resource);
-    resource.open(instance, params, callbacks);
-  }
-
-  unsubscribe(instance: string) {
-    const resource = this.instances.get(instance);
-    if (resource) {
-      resource.close(instance);
-      this.instances.delete(instance);
-    }
-  }
-
-  shutdown(): Promise<void> {
-    return Promise.resolve();
-  }
-}
-
 type Timeout = ReturnType<typeof setInterval>;
-type Timeouts = { [name: string]: Timeout };
-
-export class TimerResource implements ExternalResource {
-  private readonly intervals = new Map<string, { [name: string]: Timeout }>();
-
-  open(
-    instance: string,
-    params: Json,
-    callbacks: {
-      update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
-      error: (error: Json) => void;
-      loading: () => void;
-    },
-  ) {
-    const time = new Date().getTime();
-    const values: Entry<string, number>[] = [];
-    for (const name of Object.keys(params)) {
-      values.push([name, [time]]);
-    }
-    callbacks.update(values, true);
-    const intervals: Timeouts = {};
-    for (const [name, duration] of Object.entries(params)) {
-      const ms = Number(duration);
-      if (ms > 0) {
-        intervals[name] = setInterval(() => {
-          const newvalue: Entry<Json, Json> = [name, [new Date().getTime()]];
-          callbacks.update([newvalue], true);
-        }, ms);
-      }
-    }
-    this.intervals.set(instance, intervals);
-  }
-
-  close(instance: string): void {
-    const intervals = this.intervals.get(instance);
-    if (intervals != null) {
-      for (const interval of Object.values(intervals)) {
-        clearInterval(interval);
-      }
-      this.intervals.delete(instance);
-    }
-  }
-}
 
 /**
  * Encode params for external resource request.
@@ -134,47 +24,58 @@ export function defaultParamEncoder(params: Json): string {
 }
 
 /**
- * An external resource that is refreshed at some polling interval.
+ * Description of an external HTTP endpoint and how to poll it.
+ *
+ * The URL of the external resource is formed by appending the given base `url` and the result of `encodeParams(params)` where `params` are the parameters provided to [`Context#useExternalResource`](api/core/interfaces/Context#useexternalresource)
  *
- * @typeParam S - Type of data received from external resource.
- * @typeParam K - Type of keys.
- * @typeParam V - Type of values.
  */
-export class Polled<S extends Json, K extends Json, V extends Json>
-  implements ExternalResource
-{
+export interface PolledHTTPResource {
+  /**
+   * Base URL of resource to poll.
+   */
+  url: string;
+  /**
+   * The interval of time to wait before refreshing the data, given in milliseconds
+   */
+  interval: number;
+  /**
+   * Function to convert data received from external resource to `key`-`value` entries.
+   */
+  conv: (data: Json) => Entry<Json, Json>[];
+  /**
+   * Function to use to encode params of type `Json` for external resource request.
+   *
+   * Note that the result of `encodeParams` may contain a `?` separator, but it need not be at the beginning of the returned string, so some parameters can be used in part of the URL preceding the `?`.
+   */
+  encodeParams?: (params: Json) => string;
+  /**
+   * Optional parameters: additional `headers` to add to request, and `timeout` for request, in milliseconds. (default 1000ms)
+   */
+  options?: { headers?: { [header: string]: string }; timeout?: number };
+}
+
+/**
+ * An external HTTP service that is kept up-to-date by polling.
+ *
+ * A `PolledExternalService` may be composed of one or more [`PolledHTTPResource`](api/helpers/interfaces/PolledHTTPResource)s, each of which describes a single endpoint and how to poll it.
+ */
+export class PolledExternalService implements ExternalService {
   private readonly intervals = new Map<string, Timeout>();
 
   /**
-   * Construct a `Polled` external resource.
+   * Construct a polled external service.
    *
-   * The URL of the external resource is formed by appending the given base `url` and the result of `encodeParams(params)` where `params` are the parameters provided when instantiating the resource.
-   *
-   * Note that the result of `encodeParams` contains the `?` separator, but it need not be at the beginning of the returned string, so some parameters can be used in part of the URL preceding the `?`.
-   *
-   * @param url - HTTP endpoint of external resource to poll.
-   * @param duration - Refresh interval, in milliseconds.
-   * @param conv - Function to convert data of type `S` received from external resource to `key`-`value` entries.
-   * @param encodeParams - Function to use to encode params of type `Json` for external resource request.
-   * @param options - Optional parameters.
-   * @param options.headers - Additional headers to add to request.
-   * @param options.timeout - Timeout for request, in milliseconds. Defaults to 1000ms.
+   * @param resources - Specification(s) of external resource(s) to poll
    */
   constructor(
-    private readonly url: string,
-    private readonly duration: number,
-    private readonly conv: (data: S) => Entry<K, V>[],
-    private readonly encodeParams: (
-      params: Json,
-    ) => string = defaultParamEncoder,
-    private readonly options?: {
-      headers?: { [header: string]: string };
-      timeout?: number;
+    private readonly resources: {
+      [resource: string]: PolledHTTPResource;
     },
   ) {}
 
-  open(
+  subscribe(
     instance: string,
+    resourceName: string,
     params: Json,
     callbacks: {
       update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
@@ -182,12 +83,18 @@ export class Polled<S extends Json, K extends Json, V extends Json>
       loading: () => void;
     },
   ) {
-    const url = `${this.url}${this.encodeParams(params)}`;
+    const resource = this.resources[resourceName];
+    if (!resource)
+      throw new SkipUnknownResourceError(
+        `Unknown resource named '${resourceName}'`,
+      );
+
+    const url = `${resource.url}${(resource.encodeParams ?? defaultParamEncoder)(params)}`;
     const call = () => {
       callbacks.loading();
-      fetchJSON(url, "GET", this.options)
+      fetchJSON(url, "GET", resource.options ?? {})
         .then((r) => {
-          callbacks.update(this.conv(r[0] as S), true);
+          callbacks.update(resource.conv(r[0] ?? []), true);
         })
         .catch((e: unknown) => {
           callbacks.error(e instanceof Error ? e.message : JSON.stringify(e));
@@ -195,14 +102,22 @@ export class Polled<S extends Json, K extends Json, V extends Json>
         });
     };
     call();
-    this.intervals.set(instance, setInterval(call, this.duration));
+    this.intervals.set(instance, setInterval(call, resource.interval));
   }
 
-  close(instance: string): void {
+  unsubscribe(instance: string): void {
     const interval = this.intervals.get(instance);
     if (interval) {
       clearInterval(interval);
       this.intervals.delete(instance);
     }
   }
+
+  shutdown(): Promise<void> {
+    for (const [instance, interval] of Object.entries(this.intervals)) {
+      clearInterval(interval as Timeout);
+      this.intervals.delete(instance);
+    }
+    return Promise.resolve();
+  }
 }

package/src/index.ts

@@ -4,13 +4,7 @@
  * @packageDocumentation
  */
 
-export {
-  defaultParamEncoder,
-  type ExternalResource,
-  GenericExternalService,
-  Polled,
-  TimerResource,
-} from "./external.js";
+export { defaultParamEncoder, PolledExternalService } from "./external.js";
 export { SkipExternalService } from "./remote.js";
 export { SkipServiceBroker, fetchJSON, type Entrypoint } from "./rest.js";
 export { Count, Max, Min, Sum } from "./utils.js";