typedrest 0.5.0 → 0.6.0

package/endpoints/generic/{GenericCollectionEndpoint.ts → GenericCollectionEndpoint.d.ts}

@@ -2,53 +2,32 @@ import { ETagEndpointBase } from "./ETagEndpointBase";
 import { ElementEndpoint } from "./ElementEndpoint";
 import { PartialResponse } from "./PartialResponse";
 import { Endpoint } from "../Endpoint";
-import { CachingEndpoint } from "../CachingEndpoint";
-import { HttpMethod, HttpHeader, HttpContentRange, ResponseCache } from "../../http";
-
 /**
  * Endpoint for a collection of `TEntity`s addressable as `TElementEndpoint`s.<br>
  * Use {@link CollectionEndpoint} instead if you wish to use the default {@link ElementEndpoint} type.
  * @typeParam TEntity The type of individual elements in the collection.
  * @typeParam TElementEndpoint The type of {@link ElementEndpoint} to provide for individual `TEntity`s.
  */
-export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends ElementEndpoint<TEntity>> extends ETagEndpointBase {
+export declare class GenericCollectionEndpoint<TEntity, TElementEndpoint extends ElementEndpoint<TEntity>> extends ETagEndpointBase {
+    private readonly elementEndpoint;
     /**
      * Creates a new collection endpoint.
      * @param referrer The endpoint used to navigate to this one.
      * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
      * @param elementEndpoint A factory method for creating instances of `TElementEndpoint`.
      */
-    constructor(referrer: Endpoint, relativeUri: URL | string, private readonly elementEndpoint: new (referrer: Endpoint, uri: URL) => TElementEndpoint) {
-        super(referrer, relativeUri);
-        this.setDefaultLinkTemplate("child", "./{id}");
-    }
-
+    constructor(referrer: Endpoint, relativeUri: URL | string, elementEndpoint: new (referrer: Endpoint, uri: URL) => TElementEndpoint);
     /**
      * Returns an `TElementEndpoint` for a specific child element.
      * @param element The ID identifying the entity or an entity to extract the ID from.
      */
-    get(element: (TEntity | string)): TElementEndpoint {
-        if (element == null) throw new Error("element must not be null or unspecified.");
-
-        let id: string;
-        if (typeof element === "string") {
-            id = element;
-        } else {
-            id = (element as any).id;
-            if (id === undefined) throw new Error(`Element ${element} does not have an id property.`);
-        }
-        if (id == null || id === "") throw new Error("id must not be null or empty.");
-
-        return new this.elementEndpoint(this, this.linkTemplate("child", { id }));
-    }
-
+    get(element: (TEntity | string)): TElementEndpoint;
     /**
      * Shows whether the server has indicated that {@link readAll} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get readAllAllowed() { return this.isMethodAllowed(HttpMethod.Get); }
-
+    get readAllAllowed(): boolean | undefined;
     /**
      * Returns all `TEntity`s in the collection.
      * @param signal Used to cancel the request.
@@ -57,42 +36,22 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!ConflictError}: {@link http!HttpStatusCode.Conflict}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async readAll(signal?: AbortSignal) {
-        return this.serializer.deserialize<TEntity[]>(await this.getContent(signal));
-    }
-
+    readAll(signal?: AbortSignal): Promise<TEntity[]>;
     /**
      * The unit used when requesting ranges of elements. Sent in the {@link http!HttpHeader.Range} header.
      */
-    rangeUnit = "elements";
-
-    // NOTE: Only modified when the server reports its capabilities.
-    private acceptedRangeUnits: string[] = [];
-
+    rangeUnit: string;
+    private acceptedRangeUnits;
     /**
      * @inheritDoc
      */
-    protected handleCapabilities(response: Response) {
-        super.handleCapabilities(response);
-
-        const header = response.headers.get(HttpHeader.AcceptRanges);
-        if (header) {
-            this.acceptedRangeUnits = header.split(",").map(x => x.trim());
-        }
-    }
-
+    protected handleCapabilities(response: Response): void;
     /**
      * Shows whether the server has indicated that {@link readRange} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify accepted range units.
      */
-    get readRangeAllowed(): boolean | undefined {
-        if (this.acceptedRangeUnits.length === 0)
-            return undefined;
-
-        return this.acceptedRangeUnits.indexOf(this.rangeUnit) !== -1;
-    }
-
+    get readRangeAllowed(): boolean | undefined;
     /**
      * Returns a subset of the `TEntity`s in the collection.
      * @param from The index of the first element to return. Leave unspecified to return the last `to` elements ("tail").
@@ -103,23 +62,13 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!RangeNotSatisfiableError}: {@link http!HttpStatusCode.RangeNotSatisfiable}, i.e. the requested range lies outside of the elements currently available
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async readRange(from?: number, to?: number, signal?: AbortSignal): Promise<PartialResponse<TEntity>> {
-        const response = await this.send(HttpMethod.Get, signal, {
-            [HttpHeader.Range]: `${this.rangeUnit}=${from ?? ""}-${to ?? ""}`
-        });
-
-        return new PartialResponse<TEntity>(
-            this.serializer.deserialize<TEntity[]>(await response.text()),
-            HttpContentRange.from(response));
-    }
-
+    readRange(from?: number, to?: number, signal?: AbortSignal): Promise<PartialResponse<TEntity>>;
     /**
      * Shows whether the server has indicated that {@link create} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get createAllowed() { return this.isMethodAllowed(HttpMethod.Post); }
-
+    get createAllowed(): boolean | undefined;
     /**
      * Adds a `TEntity` as a new element to the collection.
      * @param entity The new `TEntity`.
@@ -131,37 +80,13 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!ConflictError}: {@link http!HttpStatusCode.Conflict}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async create(entity: TEntity, signal?: AbortSignal): Promise<TElementEndpoint | undefined> {
-        const response = await this.send(HttpMethod.Post, signal, {
-            [HttpHeader.ContentType]: this.serializer.supportedMediaTypes[0]
-        }, this.serializer.serialize(entity));
-        const location = response.headers.get(HttpHeader.Location);
-
-        let elementEndpoint: TElementEndpoint;
-        if (location) {
-            // Explicit element endpoint URL from "Location" header
-            elementEndpoint = new this.elementEndpoint(this, this.join(location));
-        } else {
-            try {
-                // Infer URL from entity ID in response body
-                elementEndpoint = this.get(this.serializer.deserialize(await response.clone().text()));
-            } catch {
-                // No element endpoint
-                return undefined;
-            }
-        }
-
-        (elementEndpoint as CachingEndpoint).responseCache = await ResponseCache.from(response);
-        return elementEndpoint;
-    }
-
+    create(entity: TEntity, signal?: AbortSignal): Promise<TElementEndpoint | undefined>;
     /**
      * Shows whether the server has indicated that {@link createAll} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get createAllAllowed() { return this.isMethodAllowed(HttpMethod.Patch); }
-
+    get createAllAllowed(): boolean | undefined;
     /**
      * Adds (or updates) multiple `TEntity`s as elements in the collection.
      * @param entities The `TEntity`s to create or modify.
@@ -172,19 +97,13 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!ConflictError}: {@link http!HttpStatusCode.Conflict}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async createAll(entities: TEntity[], signal?: AbortSignal) {
-        await this.send(HttpMethod.Patch, signal, {
-            [HttpHeader.ContentType]: this.serializer.supportedMediaTypes[0]
-        }, this.serializer.serialize(entities));
-    }
-
+    createAll(entities: TEntity[], signal?: AbortSignal): Promise<void>;
     /**
      * Shows whether the server has indicated that {@link setAll} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get setAllAllowed() { return this.isMethodAllowed(HttpMethod.Put); }
-
+    get setAllAllowed(): boolean | undefined;
     /**
      *  Replaces the entire content of the collection with new `TEntity`s.
      * @param entities The `TEntity`s to create or modify.
@@ -194,8 +113,7 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!ConflictError}: {@link http!HttpStatusCode.Conflict}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async setAll(entities: TEntity[]) { await this.putContent(entities); }
-
+    setAll(entities: TEntity[]): Promise<void>;
     /**
      * Determines whether the collection contains a specific element.
      * @param element The ID identifying the entity or an entity to extract the ID from.
@@ -203,8 +121,7 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    contains(element: (TEntity | string)) { return this.get(element).exists(); }
-
+    contains(element: (TEntity | string)): Promise<boolean>;
     /**
      * Sets/replaces an existing element in the collection.
      * @param element The new state of the element.
@@ -215,8 +132,7 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    set(element: TEntity) { return this.get(element).set(element); }
-
+    set(element: TEntity): Promise<TEntity | undefined>;
     /**
      * Modifies an existing element in the collection by merging changes on the server-side.
      * @param element The `TEntity` data to merge with the existing element.
@@ -227,8 +143,7 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    merge(element: TEntity) { return this.get(element).merge(element); }
-
+    merge(element: TEntity): Promise<TEntity | undefined>;
     /**
      * Deletes an existing element from the collection.
      * @param element The ID identifying the entity or an entity to extract the ID from.
@@ -237,5 +152,5 @@ export class GenericCollectionEndpoint<TEntity, TElementEndpoint extends Element
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    delete(element: (TEntity | string)) { return this.get(element).delete(); }
+    delete(element: (TEntity | string)): Promise<void>;
 }

package/endpoints/generic/{IndexerEndpoint.ts → IndexerEndpoint.d.ts}

@@ -1,27 +1,20 @@
 import { Endpoint } from "../Endpoint";
-
 /**
  * Endpoint that addresses child `TElementEndpoint`s by ID.
  * @typeParam TElementEndpoint The type of {@link Endpoint} to provide for individual elements.
  */
-export class IndexerEndpoint<TElementEndpoint extends Endpoint> extends Endpoint {
+export declare class IndexerEndpoint<TElementEndpoint extends Endpoint> extends Endpoint {
+    private readonly elementEndpoint;
     /**
      * Creates a new indexer endpoint.
      * @param referrer The endpoint used to navigate to this one.
      * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
      * @param elementEndpoint A factory method for creating instances of `TElementEndpoint`.
      */
-    constructor(referrer: Endpoint, relativeUri: URL | string, private readonly elementEndpoint: new (referrer: Endpoint, uri: URL) => TElementEndpoint) {
-        super(referrer, relativeUri);
-        this.setDefaultLinkTemplate("child", "./{id}");
-    }
-
+    constructor(referrer: Endpoint, relativeUri: URL | string, elementEndpoint: new (referrer: Endpoint, uri: URL) => TElementEndpoint);
     /**
      * Returns a `TElementEndpoint` for a specific child element.
      * @param id The ID identifying the entity.
      */
-    get(id: string): TElementEndpoint {
-        if (id == null || id === "") throw new Error("id must not be null, unspecified or empty.");
-        return new this.elementEndpoint(this, this.linkTemplate("child", { id }));
-    }
+    get(id: string): TElementEndpoint;
 }

package/endpoints/generic/PartialResponse.d.ts

@@ -0,0 +1,19 @@
+import { HttpContentRange } from "../../http";
+/**
+ * Represents a subset of a set of elements.
+ * @typeParam TEntity The type of element the response contains.
+ */
+export declare class PartialResponse<TEntity> {
+    readonly elements: TEntity[];
+    readonly range?: HttpContentRange | undefined;
+    /**
+     * Creates a new partial response.
+     * @param elements The returned elements.
+     * @param range The range the `elements` come from.
+     */
+    constructor(elements: TEntity[], range?: HttpContentRange | undefined);
+    /**
+     * Indicates whether the response reaches the end of the elements available on the server.
+     */
+    get endReached(): boolean;
+}

package/endpoints/{index.ts → index.d.ts}

@@ -1,8 +1,7 @@
-export * as generic from "./generic";
+export * as generic from "./generic";
 export * as rpc from "./rpc";
 export * as raw from "./raw";
 export * as reactive from "./reactive";
-
 export * from "./Endpoint";
 export * from "./EntryEndpoint";
 export * from "./CachingEndpoint";

package/endpoints/raw/{BlobEndpoint.ts → BlobEndpoint.d.ts}

@@ -1,19 +1,14 @@
 import { Endpoint } from "../Endpoint";
-import { HttpMethod, HttpHeader } from "../../http";
-
 /**
  * Endpoint for a binary blob that can be downloaded or uploaded.
  */
-export class BlobEndpoint extends Endpoint {
+export declare class BlobEndpoint extends Endpoint {
     /**
      * Creates a new blob endpoint.
      * @param referrer The endpoint used to navigate to this one.
      * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
      */
-    constructor(referrer: Endpoint, relativeUri: URL | string) {
-        super(referrer, relativeUri);
-    }
-
+    constructor(referrer: Endpoint, relativeUri: URL | string);
     /**
      * Queries the server about capabilities of the endpoint without performing any action.
      * @param signal Used to cancel the request.
@@ -22,17 +17,13 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async probe(signal?: AbortSignal) {
-        await this.send(HttpMethod.Options, signal);
-    }
-
+    probe(signal?: AbortSignal): Promise<void>;
     /**
      * Shows whether the server has indicated that {@link download} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get downloadAllowed() { return this.isMethodAllowed(HttpMethod.Get); }
-
+    get downloadAllowed(): boolean | undefined;
     /**
      * Downloads the blob's content.
      * @param signal Used to cancel the request.
@@ -42,18 +33,13 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async download(signal?: AbortSignal): Promise<Blob> {
-        const response = await this.send(HttpMethod.Get, signal);
-        return response.blob();
-    }
-
+    download(signal?: AbortSignal): Promise<Blob>;
     /**
      * Shows whether the server has indicated that {@link upload} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get uploadAllowed() { return this.isMethodAllowed(HttpMethod.Put); }
-
+    get uploadAllowed(): boolean | undefined;
     /**
      * Uploads data as the blob's content.
      * @param blob The blob to read the upload data from.
@@ -63,17 +49,13 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async uploadFrom(blob: Blob, signal?: AbortSignal) {
-        await this.send(HttpMethod.Put, signal, { [HttpHeader.ContentType]: blob.type }, blob);
-    }
-
+    uploadFrom(blob: Blob, signal?: AbortSignal): Promise<void>;
     /**
      * Shows whether the server has indicated that {@link delete} is currently allowed.
      * Uses cached data from last response.
      * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
      */
-    get deleteAllowed() { return this.isMethodAllowed(HttpMethod.Delete); }
-
+    get deleteAllowed(): boolean | undefined;
     /**
      * Deletes the blob from the server.
      * @param signal Used to cancel the request.
@@ -83,7 +65,5 @@ export class BlobEndpoint extends Endpoint {
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async delete(signal?: AbortSignal) {
-        await this.send(HttpMethod.Delete, signal);
-    }
+    delete(signal?: AbortSignal): Promise<void>;
 }

package/endpoints/raw/{UploadEndpoint.ts → UploadEndpoint.d.ts}

@@ -1,20 +1,16 @@
 import { Endpoint } from "../Endpoint";
-import { HttpMethod, HttpHeader } from "../../http";
-
 /**
  * Endpoint that accepts binary uploads using multi-part form encoding or raw bodies.
  */
-export class UploadEndpoint extends Endpoint {
+export declare class UploadEndpoint extends Endpoint {
+    private readonly formField?;
     /**
      * Creates a new upload endpoint.
      * @param referrer The endpoint used to navigate to this one.
      * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
      * @param formField The name of the form field to place the uploaded data into; leave unspecified to use raw bodies instead of a multi-part forms.
      */
-    constructor(referrer: Endpoint, relativeUri: URL | string, private readonly formField?: string) {
-        super(referrer, relativeUri);
-    }
-
+    constructor(referrer: Endpoint, relativeUri: URL | string, formField?: string | undefined);
     /**
      * Uploads data to the endpoint.
      * @param blob The blob or file to read the upload data from.
@@ -25,15 +21,5 @@ export class UploadEndpoint extends Endpoint {
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async uploadFrom(blob: Blob | File, signal?: AbortSignal) {
-        const fileName = blob instanceof File ? blob.name : undefined;
-
-        if (this.formField) {
-            const formData = new FormData();
-            formData.set(this.formField, blob, fileName);
-            await this.send(HttpMethod.Post, signal, undefined, formData);
-        } else {
-            await this.send(HttpMethod.Post, signal, { [HttpHeader.ContentType]: blob.type }, blob);
-        }
-    }
+    uploadFrom(blob: Blob | File, signal?: AbortSignal): Promise<void>;
 }

package/endpoints/reactive/Delay.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Waits for a specific amount of time.
+ * @param ms The time to wait in milliseconds.
+ * @param signal Used to cancel the wait.
+ * @returns `true` if the time has elapsed; `false` if the wait was cancelled via the `signal`.
+ */
+export declare function delay(ms: number, signal?: AbortSignal): Promise<boolean>;

package/endpoints/reactive/GenericStreamingCollectionEndpoint.d.ts

@@ -0,0 +1,32 @@
+import { ElementEndpoint } from "../generic/ElementEndpoint";
+import { GenericCollectionEndpoint } from "../generic/GenericCollectionEndpoint";
+/**
+ * Endpoint for a collection of `TEntity`s observable as an append-only stream using long-polling.<br>
+ * Use {@link StreamingCollectionEndpoint} instead if you wish to use the default {@link ElementEndpoint} type.
+ * @typeParam TEntity The type of individual elements in the collection.
+ * @typeParam TElementEndpoint The type of {@link ElementEndpoint} to provide for individual `TEntity`s.
+ */
+export declare class GenericStreamingCollectionEndpoint<TEntity, TElementEndpoint extends ElementEndpoint<TEntity>> extends GenericCollectionEndpoint<TEntity, TElementEndpoint> {
+    /**
+     * The interval in milliseconds to wait between polling requests.
+     * Automatically updated whenever the server sends a {@link http!HttpHeader.RetryAfter} header.
+     */
+    pollingInterval: number;
+    /**
+     * @inheritDoc
+     */
+    protected handle(response: Response): Promise<void>;
+    /**
+     * Provides a stream of `TEntity`s, polling the server for elements appended to the collection.
+     * @param startIndex The index of the first element to return. Use a negative value to start with the last `-startIndex` elements ("tail").
+     * @param signal Used to stop polling.
+     * @throws {@link errors!AuthenticationError}: {@link http!HttpStatusCode.Unauthorized}
+     * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
+     * @throws {@link errors!HttpError}: Other non-success status code
+     */
+    stream(startIndex?: number, signal?: AbortSignal): AsyncIterableIterator<TEntity>;
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<TEntity>;
+}

package/endpoints/reactive/{PollingEndpoint.ts → PollingEndpoint.d.ts}

@@ -1,37 +1,27 @@
 import { ElementEndpoint } from "../generic/ElementEndpoint";
 import { Endpoint } from "../Endpoint";
-import { delay } from "./Delay";
-import { retryAfter } from "../../http";
-
 /**
  * Endpoint for a resource that can be polled for state changes.
  * @typeParam TEntity The type of entity the endpoint represents.
  */
-export class PollingEndpoint<TEntity> extends ElementEndpoint<TEntity> {
+export declare class PollingEndpoint<TEntity> extends ElementEndpoint<TEntity> {
+    private readonly endCondition?;
     /**
      * Creates a new polling endpoint.
      * @param referrer The endpoint used to navigate to this one.
      * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
      * @param endCondition A check to determine whether the entity has reached its final state and no further polling is required.
      */
-    constructor(referrer: Endpoint, relativeUri: URL | string, private readonly endCondition?: (entity: TEntity) => boolean) {
-        super(referrer, relativeUri);
-    }
-
+    constructor(referrer: Endpoint, relativeUri: URL | string, endCondition?: ((entity: TEntity) => boolean) | undefined);
     /**
      * The interval in milliseconds to wait between polling requests.
      * Automatically updated whenever the server sends a {@link http!HttpHeader.RetryAfter} header.
      */
-    pollingInterval = 3000;
-
+    pollingInterval: number;
     /**
      * @inheritDoc
      */
-    protected async handle(response: Response) {
-        await super.handle(response);
-        this.pollingInterval = retryAfter(response) ?? this.pollingInterval;
-    }
-
+    protected handle(response: Response): Promise<void>;
     /**
      * Provides a stream of the `TEntity`'s states, polling the server for changes.
      * States that are identical to the previously provided one are skipped.
@@ -41,26 +31,9 @@ export class PollingEndpoint<TEntity> extends ElementEndpoint<TEntity> {
      * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
      * @throws {@link errors!HttpError}: Other non-success status code
      */
-    async *stream(signal?: AbortSignal): AsyncIterableIterator<TEntity> {
-        // NOTE: Compare the serialized form because every poll deserializes a new object instance.
-        let previous: string | undefined;
-
-        while (!signal?.aborted) {
-            const entity = await this.read(signal);
-
-            const serialized = this.serializer.serialize(entity);
-            if (serialized !== previous) {
-                previous = serialized;
-                yield entity;
-            }
-
-            if (this.endCondition?.(entity)) return;
-            if (!await delay(this.pollingInterval, signal)) return;
-        }
-    }
-
+    stream(signal?: AbortSignal): AsyncIterableIterator<TEntity>;
     /**
      * Provides a stream of the `TEntity`'s states using {@link stream}.
      */
-    [Symbol.asyncIterator]() { return this.stream(); }
+    [Symbol.asyncIterator](): AsyncIterableIterator<TEntity>;
 }

package/endpoints/reactive/SseStreamingEndpoint.d.ts

@@ -0,0 +1,50 @@
+import { Endpoint } from "../Endpoint";
+/**
+ * Endpoint for a stream of `TEntity`s using Server-Sent Events (SSE).<br>
+ * Sends `Accept: text/event-stream`. By default, transparently reconnects on connection drops or transient errors,
+ * honoring the server-supplied `retry:` interval and resuming via the {@link http!HttpHeader.LastEventId} header.
+ * @typeParam TEntity The type of individual elements in the stream.
+ */
+export declare class SseStreamingEndpoint<TEntity> extends Endpoint {
+    private readonly eventType?;
+    /**
+     * Creates a new SSE streaming endpoint.
+     * @param referrer The endpoint used to navigate to this one.
+     * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
+     * @param eventType If set, only events with this `event:` type are provided; others are ignored. Leave unspecified to provide all events.
+     */
+    constructor(referrer: Endpoint, relativeUri: URL | string, eventType?: string | undefined);
+    /**
+     * Whether to transparently reconnect on connection drops, transient transport errors and 5xx responses.
+     */
+    autoReconnect: boolean;
+    /**
+     * The reconnection interval in milliseconds used when the server has not (yet) supplied one via the SSE `retry:` field.
+     */
+    defaultReconnectionInterval: number;
+    /**
+     * Provides a stream of `TEntity`s, reconnecting as needed unless {@link autoReconnect} is disabled.
+     * @param signal Used to close the connection.
+     * @throws {@link errors!AuthenticationError}: {@link http!HttpStatusCode.Unauthorized}
+     * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
+     * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
+     * @throws {@link errors!HttpError}: Other non-success status code
+     */
+    stream(signal?: AbortSignal): AsyncIterableIterator<TEntity>;
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<TEntity>;
+    /**
+     * Opens a connection and provides events until the stream ends.
+     * @param state Carries the last event id and the reconnection interval over to the next attempt.
+     * @param signal Used to close the connection.
+     * @returns `true` if another connection attempt should be made; `false` if the stream has ended for good.
+     */
+    private consumeOnce;
+    /**
+     * Determines whether an error is a transport-level failure that may succeed on a retry.
+     * The Fetch API reports these as `TypeError`s, while responses the server actually sent become {@link errors!HttpError}s.
+     */
+    private static isTransient;
+}

package/endpoints/reactive/{StreamingCollectionEndpoint.ts → StreamingCollectionEndpoint.d.ts}

@@ -1,20 +1,17 @@
 import { GenericStreamingCollectionEndpoint } from "./GenericStreamingCollectionEndpoint";
 import { ElementEndpoint } from "../generic/ElementEndpoint";
 import { Endpoint } from "../Endpoint";
-
 /**
  * Endpoint for a collection of `TEntity`s observable as an append-only stream using long-polling,
  * addressable as {@link ElementEndpoint}s.<br>
  * Use {@link GenericStreamingCollectionEndpoint} instead if you wish to customize the element endpoint type.
  * @typeParam TEntity The type of individual elements in the collection.
  */
-export class StreamingCollectionEndpoint<TEntity> extends GenericStreamingCollectionEndpoint<TEntity, ElementEndpoint<TEntity>> {
+export declare class StreamingCollectionEndpoint<TEntity> extends GenericStreamingCollectionEndpoint<TEntity, ElementEndpoint<TEntity>> {
     /**
      * Creates a new streaming collection endpoint.
      * @param referrer The endpoint used to navigate to this one.
      * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
      */
-    constructor(referrer: Endpoint, relativeUri: URL | string) {
-        super(referrer, relativeUri, ElementEndpoint);
-    }
+    constructor(referrer: Endpoint, relativeUri: URL | string);
 }