@skipruntime/helpers 0.0.5 → 0.0.7

package/src/rest.ts

@@ -7,9 +7,24 @@ import { NonUniqueValueException } from "@skipruntime/api";
  * URLs for the service's control and streaming APIs can be constructed from an `Entrypoint`.
  */
 export type Entrypoint = {
+  /**
+   * Hostname of the service.
+   */
   host: string;
+
+  /**
+   * Port to use for the service's streaming interface.
+   */
   streaming_port: number;
+
+  /**
+   * Port to use for the service's control interface.
+   */
   control_port: number;
+
+  /**
+   * Flag that when set indicates that https should be used instead of http.
+   */
   secured?: boolean;
 };
 
@@ -19,20 +34,38 @@ function toHttp(entrypoint: Entrypoint) {
   return `http://${entrypoint.host}:${entrypoint.control_port}`;
 }
 
+/**
+ * Perform an HTTP fetch where input and output data is `Json`.
+ *
+ * @typeParam V - Type response is *assumed* to have.
+ * @param url - URL from which to fetch.
+ * @param method - HTTP method of request.
+ * @param options - Optional parameters.
+ * @param options.headers - Additional headers to add to request.
+ * @param options.body - Data to convert to JSON and send in request body.
+ * @param options.timeout - Timeout for request, in milliseconds. Defaults to 1000ms.
+ * @returns Response parsed as JSON, and headers.
+ */
 export async function fetchJSON<V extends Json>(
   url: string,
   method: "POST" | "GET" | "PUT" | "PATCH" | "HEAD" | "DELETE" = "GET",
-  headers: { [header: string]: string } = {},
-  data?: Json,
+  options: {
+    headers?: { [header: string]: string };
+    body?: Json;
+    timeout?: number;
+  } = {
+    headers: {},
+    timeout: 1000,
+  },
 ): Promise<[V | null, Headers]> {
-  const body = data ? JSON.stringify(data) : undefined;
+  const body = options.body ? JSON.stringify(options.body) : undefined;
   const response = await fetch(url, {
     method,
     body,
     headers: {
       "Content-Type": "application/json",
       Accept: "application/json",
-      ...headers,
+      ...options.headers,
     },
     signal: AbortSignal.timeout(1000),
   });
@@ -58,8 +91,9 @@ export class SkipServiceBroker {
 
   /**
    * Construct a broker for a Skip service at the given entry point.
-   * @param entrypoint - entry point of backing service
-   * @returns - method-call broker to service
+   *
+   * @param entrypoint - Entry point of backing service.
+   * @returns Method-call broker to service.
    */
   constructor(
     entrypoint: Entrypoint = {
@@ -74,58 +108,64 @@ export class SkipServiceBroker {
   /**
    * Read the entire contents of a resource.
    *
-   * @param resource - name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`
-   * @param params - resource instance parameters
-   * @returns - all entries in resource
+   * @typeParam K - Type of keys.
+   * @typeParam V - Type of values.
+   * @param resource - Name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`.
+   * @param params - Resource instance parameters.
+   * @returns All entries in resource.
    */
   async getAll<K extends Json, V extends Json>(
     resource: string,
-    params: { [param: string]: string },
+    params: Json,
   ): Promise<Entry<K, V>[]> {
     const [data, _headers] = await fetchJSON<Entry<K, V>[]>(
-      `${this.entrypoint}/v1/snapshot`,
+      `${this.entrypoint}/v1/snapshot/${resource}`,
       "POST",
-      {},
-      { resource, params },
+      { body: params },
     );
     return data ?? [];
   }
 
   /**
    * Read the values a resource associates with a single key.
-   * @param resource - name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`
-   * @param params - resource instance parameters
-   * @param key - key to read
-   * @returns - the values associated to the key
+   *
+   * @typeParam K - Type of keys.
+   * @typeParam V - Type of values.
+   * @param resource - Name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`.
+   * @param params - Resource instance parameters.
+   * @param key - Key to read.
+   * @returns The values associated to the key.
    */
-  async getArray<V extends Json>(
+  async getArray<K extends Json, V extends Json>(
     resource: string,
-    params: { [param: string]: string },
-    key: string,
+    params: Json,
+    key: K,
   ): Promise<V[]> {
     const [data, _headers] = await fetchJSON<V[]>(
-      `${this.entrypoint}/v1/snapshot`,
+      `${this.entrypoint}/v1/snapshot/${resource}/lookup`,
       "POST",
-      {},
-      { resource, key, params },
+      { body: { key, params } },
     );
     return data ?? [];
   }
 
   /**
    * Read the single value a resource associates with a key.
-   * @param resource - name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`
-   * @param params - resource instance parameters
-   * @param key - key to read
-   * @returns - the value associated to the key
-   * @throws {NonUniqueValueException} when the key is associated to either zero or multiple values
+   *
+   * @typeParam K - Type of keys.
+   * @typeParam V - Type of values.
+   * @param resource - Name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`.
+   * @param params - Resource instance parameters.
+   * @param key - Key to read.
+   * @returns The value associated to the key.
+   * @throws `NonUniqueValueException` when the key is associated to either zero or multiple values.
    */
-  async getUnique<V extends Json>(
+  async getUnique<K extends Json, V extends Json>(
     resource: string,
-    params: { [param: string]: string },
-    key: string,
+    params: Json,
+    key: K,
   ): Promise<V> {
-    return this.getArray<V>(resource, params, key).then((values) => {
+    return this.getArray<K, V>(resource, params, key).then((values) => {
       if (values.length !== 1 || values[0] === undefined)
         throw new NonUniqueValueException();
       return values[0];
@@ -134,9 +174,12 @@ export class SkipServiceBroker {
 
   /**
    * Write the values for a single key in a collection.
-   * @param collection - name of the input collection to update, must be a key of the `Inputs` type parameter of the `SkipService` running at `entrypoint`
-   * @param key - key of entry to write
-   * @param values - values of entry to write
+   *
+   * @typeParam K - Type of keys.
+   * @typeParam V - Type of values.
+   * @param collection - Name of the input collection to update, must be a key of the `Inputs` type parameter of the `SkipService` running at `entrypoint`.
+   * @param key - Key of entry to write.
+   * @param values - Values of entry to write.
    * @returns {void}
    */
   async put<K extends Json, V extends Json>(
@@ -149,26 +192,28 @@ export class SkipServiceBroker {
 
   /**
    * Write multiple entries to a collection.
-   * @param collection - name of the input collection to update, must be a key of the `Inputs` type parameter of the `SkipService` running at `entrypoint`
-   * @param entries - entries to write
+   *
+   * @typeParam K - Type of keys.
+   * @typeParam V - Type of values.
+   * @param collection - Name of the input collection to update, must be a key of the `Inputs` type parameter of the `SkipService` running at `entrypoint`.
+   * @param entries - Entries to write.
    * @returns {void}
    */
   async patch<K extends Json, V extends Json>(
     collection: string,
     entries: Entry<K, V>[],
   ): Promise<void> {
-    await fetchJSON(
-      `${this.entrypoint}/v1/inputs/${collection}`,
-      "PATCH",
-      {},
-      entries,
-    );
+    await fetchJSON(`${this.entrypoint}/v1/inputs/${collection}`, "PATCH", {
+      body: entries,
+    });
   }
 
   /**
    * Remove all values associated with a key in a collection.
-   * @param collection - name of the input collection to update, must be a key of the `Inputs` type parameter of the `SkipService` running at `entrypoint`
-   * @param key - key of entry to delete
+   *
+   * @typeParam K - Type of keys.
+   * @param collection - Name of the input collection to update, must be a key of the `Inputs` type parameter of the `SkipService` running at `entrypoint`.
+   * @param key - Key of entry to delete.
    * @returns {void}
    */
   async deleteKey<K extends Json>(collection: string, key: K): Promise<void> {
@@ -177,18 +222,18 @@ export class SkipServiceBroker {
 
   /**
    * Create a resource instance UUID.
-   * @param resource - name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`
-   * @param params - resource instance parameters
-   * @returns - UUID that can be used to subscribe to updates to resource instance
+   *
+   * @typeParam K - Type of keys.
+   * @typeParam V - Type of values.
+   * @param resource - Name of resource, must be a key of the `resources` field of the `SkipService` running at `entrypoint`.
+   * @param params - Resource instance parameters.
+   * @returns UUID that can be used to subscribe to updates to resource instance.
    */
-  async getStreamUUID(
-    resource: string,
-    params: { [param: string]: string } = {},
-  ): Promise<string> {
-    return fetch(`${this.entrypoint}/v1/streams`, {
+  async getStreamUUID(resource: string, params: Json = {}): Promise<string> {
+    return fetch(`${this.entrypoint}/v1/streams/${resource}`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ resource, params }),
+      body: JSON.stringify(params),
     }).then((res) => res.text());
   }
 
@@ -197,7 +242,7 @@ export class SkipServiceBroker {
    *
    * Under normal circumstances, resource instances are deleted automatically after some period of inactivity; this method enables immediately deleting live streams under exceptional circumstances.
    *
-   * @param uuid - resource instance UUID
+   * @param uuid - Resource instance UUID.
    * @returns {void}
    */
   async deleteUUID(uuid: string): Promise<void> {