@skipruntime/helpers 0.0.5 → 0.0.7

package/dist/rest.js

@@ -4,15 +4,30 @@ function toHttp(entrypoint) {
         return `https://${entrypoint.host}:${entrypoint.control_port}`;
     return `http://${entrypoint.host}:${entrypoint.control_port}`;
 }
-export async function fetchJSON(url, method = "GET", headers = {}, data) {
-    const body = data ? JSON.stringify(data) : undefined;
+/**
+ * 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(url, method = "GET", options = {
+    headers: {},
+    timeout: 1000,
+}) {
+    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),
     });
@@ -34,8 +49,9 @@ export async function fetchJSON(url, method = "GET", headers = {}, data) {
 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 = {
         host: "localhost",
@@ -47,32 +63,40 @@ 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(resource, params) {
-        const [data, _headers] = await fetchJSON(`${this.entrypoint}/v1/snapshot`, "POST", {}, { resource, params });
+        const [data, _headers] = await fetchJSON(`${this.entrypoint}/v1/snapshot/${resource}`, "POST", { 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(resource, params, key) {
-        const [data, _headers] = await fetchJSON(`${this.entrypoint}/v1/snapshot`, "POST", {}, { resource, key, params });
+        const [data, _headers] = await fetchJSON(`${this.entrypoint}/v1/snapshot/${resource}/lookup`, "POST", { 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(resource, params, key) {
         return this.getArray(resource, params, key).then((values) => {
@@ -83,9 +107,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(collection, key, values) {
@@ -93,17 +120,24 @@ 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(collection, entries) {
-        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(collection, key) {
@@ -111,15 +145,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, params = {}) {
-        return fetch(`${this.entrypoint}/v1/streams`, {
+        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());
     }
     /**
@@ -127,7 +164,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) {

package/dist/rest.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skipruntime/helpers",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -21,7 +21,8 @@
   "dependencies": {
     "eventsource": "^2.0.2",
     "express": "^4.21.1",
-    "@skipruntime/api": "^0.0.4"
+    "@skipruntime/core": "^0.0.4",
+    "@skipruntime/api": "^0.0.5"
   },
   "devDependencies": {
     "@types/eventsource": "^1.1.15"

package/src/external.ts

@@ -1,9 +1,12 @@
 import type { Entry, ExternalService, Json } from "@skipruntime/api";
 import { fetchJSON } from "./rest.js";
 
+/**
+ * Interface required by `GenericExternalService` for external resources.
+ */
 export interface ExternalResource {
   open(
-    params: { [param: string]: string | number },
+    params: Json,
     callbacks: {
       update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
       error: (error: Json) => void;
@@ -11,17 +14,25 @@ export interface ExternalResource {
     },
   ): void;
 
-  close(params: { [param: string]: string | number }): void;
+  close(params: Json): 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 {
+  /**
+   * @param resources - Association of resource names to `ExternalResource`s.
+   */
   constructor(
     private readonly resources: { [name: string]: ExternalResource },
   ) {}
 
   subscribe(
     resourceName: string,
-    params: { [param: string]: string | number },
+    params: Json,
     callbacks: {
       update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
       error: (error: Json) => void;
@@ -37,7 +48,7 @@ export class GenericExternalService implements ExternalService {
     resource.open(params, callbacks);
   }
 
-  unsubscribe(resourceName: string, params: { [param: string]: string }) {
+  unsubscribe(resourceName: string, params: Json) {
     const resource = this.resources[resourceName] as
       | ExternalResource
       | undefined;
@@ -58,7 +69,7 @@ export class TimerResource implements ExternalResource {
   private readonly intervals = new Map<string, { [name: string]: Timeout }>();
 
   open(
-    params: { [param: string]: string | number },
+    params: Json,
     callbacks: {
       update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
       error: (error: Json) => void;
@@ -85,7 +96,7 @@ export class TimerResource implements ExternalResource {
     this.intervals.set(id, intervals);
   }
 
-  close(params: { [param: string]: string | number }): void {
+  close(params: Json): void {
     const intervals = this.intervals.get(toId(params));
     if (intervals != null) {
       for (const interval of Object.values(intervals)) {
@@ -95,19 +106,46 @@ export class TimerResource implements ExternalResource {
   }
 }
 
+function defaultParamEncoder(params: Json): string {
+  if (typeof params == "object") {
+    const queryParams: { [param: string]: string } = {};
+    for (const [key, value] of Object.entries(params)) {
+      if (typeof value == "object") queryParams[key] = JSON.stringify(value);
+      else queryParams[key] = value.toString();
+    }
+    return new URLSearchParams(queryParams).toString();
+  } else return `params=${JSON.stringify(params)}`;
+}
+
+/**
+ * An external resource that is refreshed at some polling interval.
+ *
+ * @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
 {
   private readonly intervals = new Map<string, Timeout>();
 
+  /**
+   * @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.
+   */
   constructor(
     private readonly url: string,
     private readonly duration: number,
     private readonly conv: (data: S) => Entry<K, V>[],
+    private readonly encodeParams: (
+      params: Json,
+    ) => string = defaultParamEncoder,
   ) {}
 
   open(
-    params: { [param: string]: string | number },
+    params: Json,
     callbacks: {
       update: (updates: Entry<Json, Json>[], isInit: boolean) => void;
       error: (error: Json) => void;
@@ -115,12 +153,7 @@ export class Polled<S extends Json, K extends Json, V extends Json>
     },
   ): void {
     this.close(params);
-    const queryParams: { [param: string]: string } = {};
-    for (const [key, value] of Object.entries(params)) {
-      queryParams[key] = value.toString();
-    }
-    const strParams = new URLSearchParams(queryParams).toString();
-    const url = `${this.url}?${strParams}`;
+    const url = `${this.url}?${this.encodeParams(params)}`;
     const call = () => {
       callbacks.loading();
       fetchJSON(url, "GET", {})
@@ -136,7 +169,7 @@ export class Polled<S extends Json, K extends Json, V extends Json>
     this.intervals.set(toId(params), setInterval(call, this.duration));
   }
 
-  close(params: { [param: string]: string | number }): void {
+  close(params: Json): void {
     const interval = this.intervals.get(toId(params));
     if (interval) {
       clearInterval(interval);
@@ -144,9 +177,11 @@ export class Polled<S extends Json, K extends Json, V extends Json>
   }
 }
 
-function toId(params: { [param: string]: string | number }): string {
-  const strparams = Object.entries(params)
-    .map(([key, value]) => `${key}:${value.toString()}`)
-    .sort();
-  return `[${strparams.join(",")}]`;
+function toId(params: Json): string {
+  if (typeof params == "object") {
+    const strparams = Object.entries(params)
+      .map(([key, value]) => `${key}:${btoa(JSON.stringify(value))}`)
+      .sort();
+    return `[${strparams.join(",")}]`;
+  } else return btoa(JSON.stringify(params));
 }

package/src/index.ts

@@ -1,6 +1,14 @@
+/**
+ * This package contains items that may be useful for working with the Skip framework, but are not strictly necessary.
+ *
+ * @packageDocumentation
+ */
+
 export {
   type ExternalResource,
   GenericExternalService,
   Polled,
 } from "./external.js";
-export { fetchJSON, SkipServiceBroker } from "./rest.js";
+export { SkipExternalService } from "./remote.js";
+export { SkipServiceBroker, fetchJSON, type Entrypoint } from "./rest.js";
+export { Count, Max, Min, Sum } from "@skipruntime/core";

package/src/remote.ts

@@ -0,0 +1,109 @@
+// TODO: Remove once global `EventSource` makes it out of experimental
+// in nodejs LTS.
+import EventSource from "eventsource";
+
+import type { Entry, ExternalService, Json } from "@skipruntime/api";
+
+import type { Entrypoint } from "./rest.js";
+
+interface Closable {
+  close(): void;
+}
+
+/**
+ * An external Skip reactive service.
+ *
+ * `SkipExternalService` provides an implementation of `ExternalService` for an external Skip service.
+ */
+export class SkipExternalService implements ExternalService {
+  private readonly resources = new Map<string, Closable>();
+
+  /**
+   * @param url - URL to use for the service's streaming interface.
+   * @param control_url - URL to use for the service's control interface.
+   */
+  constructor(
+    private readonly url: string,
+    private readonly control_url: string,
+  ) {}
+
+  /**
+   * Constructor accepting an `Entrypoint`.
+   *
+   * @param entrypoint - The entry point for the external Skip service.
+   * @returns An `ExternalService` to interact with the service running at `entrypoint`.
+   */
+  // TODO: Support Skip external services going through a gateway.
+  static direct(entrypoint: Entrypoint): SkipExternalService {
+    let url = `http://${entrypoint.host}:${entrypoint.streaming_port.toString()}`;
+    let control_url = `http://${entrypoint.host}:${entrypoint.control_port.toString()}`;
+    if (entrypoint.secured) {
+      url = `https://${entrypoint.host}:${entrypoint.streaming_port.toString()}`;
+      control_url = `https://${entrypoint.host}:${entrypoint.control_port.toString()}`;
+    }
+    return new SkipExternalService(url, control_url);
+  }
+
+  subscribe(
+    resource: string,
+    params: Json,
+    callbacks: {
+      update: (updates: Entry<Json, Json>[], isInitial: boolean) => void;
+      // FIXME: What is `error()` used for?
+      error: (error: Json) => void;
+      // FIXME: What is `loading()` used for?
+      loading: () => void;
+    },
+  ): void {
+    // TODO Manage Status
+    fetch(`${this.control_url}/v1/streams`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        resource,
+        params,
+      }),
+    })
+      .then((resp) => resp.text())
+      .then((uuid) => {
+        const evSource = new EventSource(`${this.url}/v1/streams/${uuid}`);
+        evSource.addEventListener("init", (e: MessageEvent<string>) => {
+          const updates = JSON.parse(e.data) as Entry<Json, Json>[];
+          callbacks.update(updates, true);
+        });
+        evSource.addEventListener("update", (e: MessageEvent<string>) => {
+          const updates = JSON.parse(e.data) as Entry<Json, Json>[];
+          callbacks.update(updates, false);
+        });
+        evSource.onerror = (e) => {
+          console.log(e);
+        };
+        this.resources.set(this.toId(resource, params), evSource);
+      })
+      .catch((e: unknown) => {
+        console.log(e);
+      });
+  }
+
+  unsubscribe(resource: string, params: Json) {
+    const closable = this.resources.get(this.toId(resource, params));
+    if (closable) closable.close();
+  }
+
+  shutdown(): void {
+    for (const res of this.resources.values()) {
+      res.close();
+    }
+  }
+
+  private toId(resource: string, params: Json): string {
+    if (typeof params == "object") {
+      const strparams = Object.entries(params)
+        .map(([key, value]) => `${key}:${btoa(JSON.stringify(value))}`)
+        .sort();
+      return `${resource}[${strparams.join(",")}]`;
+    } else return `${resource}[${btoa(JSON.stringify(params))}]`;
+  }
+}