@skipruntime/core 0.0.2 → 0.0.3

package/src/index.ts

@@ -1,3 +1,10 @@
+/**
+ * The @skipruntime/core package contains internal implementation detail for the Skip Framework and should not need to be used directly. See the public API exposed by the @skipruntime/helpers package.
+ *
+ * @packageDocumentation
+ */
+
+import type { Opaque } from "@skiplang/std";
 import type {
   Pointer,
   Nullable,
@@ -5,7 +12,12 @@ import type {
   JsonConverter,
   JsonObject,
 } from "@skiplang/json";
-import { isObjectProxy, sk_freeze, isSkFrozen } from "@skiplang/json";
+import {
+  sk_freeze,
+  isSkManaged,
+  SkManaged,
+  checkOrCloneParam,
+} from "@skiplang/json";
 import type * as Internal from "./internal.js";
 import {
   NonUniqueValueException,
@@ -18,16 +30,14 @@ import {
   type LazyCompute,
   type Mapper,
   type NamedCollections,
-  type NonEmptyIterator,
-  type Param,
+  type Values,
+  type DepSafe,
   type Reducer,
   type Resource,
   type SkipService,
-  type SubscriptionID,
   type Watermark,
 } from "@skipruntime/api";
 
-import { Frozen } from "@skipruntime/api/internals.js";
 import { UnknownCollectionError } from "./errors.js";
 import {
   ResourceBuilder,
@@ -37,99 +47,40 @@ import {
   type FromBinding,
 } from "./binding.js";
 
-export { UnknownCollectionError, sk_freeze, isSkFrozen };
+export { UnknownCollectionError, sk_freeze, isSkManaged };
 export { SkipExternalService } from "./remote.js";
-export { Sum, Min, Max, CountMapper } from "./utils.js";
+export { Sum, Min, Max, Count, CountMapper } from "./utils.js";
 
 export type JSONMapper = Mapper<Json, Json, Json, Json>;
 export type JSONLazyCompute = LazyCompute<Json, Json>;
 
+/**
+ * An entry point of a Skip reactive service.
+ *
+ * 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;
 };
 
-abstract class SkFrozen extends Frozen {
-  protected freeze() {
-    sk_freeze(this);
-  }
-}
-
-function checkOrCloneParam<T>(value: T): T {
-  if (
-    typeof value == "string" ||
-    typeof value == "number" ||
-    typeof value == "boolean"
-  )
-    return value;
-  if (typeof value == "object") {
-    if (value === null) return value;
-    if (isObjectProxy(value)) return value.clone() as T;
-    if (isSkFrozen(value)) return value;
-    throw new Error("Invalid object: must be deep-frozen.");
-  }
-  throw new Error(`'${typeof value}' cannot be deep-frozen.`);
-}
-
-/**
- * _Deep-freeze_ an object, returning the same object that was passed in.
- *
- * This function is similar to
- * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze | `Object.freeze()`}
- * but freezes the object and deep-freezes all its properties,
- * recursively. The object is then not only _immutable_ but also
- * _constant_. Note that as a result all objects reachable from the
- * parameter will be frozen and no longer mutable or extensible, even from
- * other references.
- *
- * The argument object and all its properties, recursively, must not already
- * be frozen by `Object.freeze` (or else `deepFreeze` cannot mark them
- * deep-frozen). Undefined, function (and hence class) values cannot be
- * deep-frozen.
- *
- * The primary use for this function is to satisfy the requirement that all
- * parameters to Skip `Mapper` constructors must be deep-frozen: objects
- * that have not been constructed by Skip can be passed to `deepFreeze()`
- * before passing them to a `Mapper` constructor.
- *
- * @param value - The object to deep-freeze.
- * @returns The same object that was passed in.
- */
-export function deepFreeze<T>(value: T): T & Param {
-  if (
-    typeof value == "bigint" ||
-    typeof value == "boolean" ||
-    typeof value == "number" ||
-    typeof value == "string" ||
-    typeof value == "symbol"
-  ) {
-    return value;
-  } else if (typeof value == "object") {
-    if (value === null) {
-      return value;
-    } else if (isSkFrozen(value)) {
-      return value;
-    } else if (Object.isFrozen(value)) {
-      throw new Error(`Cannot deep-freeze an Object.frozen value.`);
-    } else if (Array.isArray(value)) {
-      for (const elt of value) {
-        deepFreeze(elt);
-      }
-      return Object.freeze(sk_freeze(value));
-    } else {
-      for (const val of Object.values(value)) {
-        deepFreeze(val);
-      }
-      return Object.freeze(sk_freeze(value));
-    }
-  } else {
-    // typeof value == "function" || typeof value == "undefined"
-    throw new Error(`'${typeof value}' values cannot be deep-frozen.`);
-  }
-}
-
 class Handles {
   private nextID: number = 1;
   private readonly objects: any[] = [];
@@ -187,7 +138,7 @@ export class Refs {
 }
 
 class LazyCollectionImpl<K extends Json, V extends Json>
-  extends SkFrozen
+  extends SkManaged
   implements LazyCollection<K, V>
 {
   constructor(
@@ -198,29 +149,29 @@ class LazyCollectionImpl<K extends Json, V extends Json>
     Object.freeze(this);
   }
 
-  getArray(key: K): (V & Param)[] {
+  getArray(key: K): (V & DepSafe)[] {
     return this.refs.skjson.importJSON(
       this.refs.binding.SkipRuntime_LazyCollection__getArray(
         this.lazyCollection,
         this.refs.skjson.exportJSON(key),
       ),
-    ) as (V & Param)[];
+    ) as (V & DepSafe)[];
   }
 
-  getUnique(key: K): V & Param {
+  getUnique(key: K): V & DepSafe {
     const v = this.refs.skjson.importOptJSON(
       this.refs.binding.SkipRuntime_LazyCollection__getUnique(
         this.lazyCollection,
         this.refs.skjson.exportJSON(key),
       ),
-    ) as Nullable<V & Param>;
+    ) as Nullable<V & DepSafe>;
     if (v == null) throw new NonUniqueValueException();
     return v;
   }
 }
 
 class EagerCollectionImpl<K extends Json, V extends Json>
-  extends SkFrozen
+  extends SkManaged
   implements EagerCollection<K, V>
 {
   constructor(
@@ -231,22 +182,22 @@ class EagerCollectionImpl<K extends Json, V extends Json>
     Object.freeze(this);
   }
 
-  getArray(key: K): (V & Param)[] {
+  getArray(key: K): (V & DepSafe)[] {
     return this.refs.skjson.importJSON(
       this.refs.binding.SkipRuntime_Collection__getArray(
         this.collection,
         this.refs.skjson.exportJSON(key),
       ),
-    ) as (V & Param)[];
+    ) as (V & DepSafe)[];
   }
 
-  getUnique(key: K): V & Param {
+  getUnique(key: K): V & DepSafe {
     const v = this.refs.skjson.importOptJSON(
       this.refs.binding.SkipRuntime_Collection__getUnique(
         this.collection,
         this.refs.skjson.exportJSON(key),
       ),
-    ) as Nullable<V & Param>;
+    ) as Nullable<V & DepSafe>;
     if (v == null) throw new NonUniqueValueException();
     return v;
   }
@@ -277,7 +228,7 @@ class EagerCollectionImpl<K extends Json, V extends Json>
     return this.derive<K, V>(skcollection);
   }
 
-  map<K2 extends Json, V2 extends Json, Params extends Param[]>(
+  map<K2 extends Json, V2 extends Json, Params extends DepSafe[]>(
     mapper: new (...params: Params) => Mapper<K, V, K2, V2>,
     ...params: Params
   ): EagerCollection<K2, V2> {
@@ -297,11 +248,11 @@ class EagerCollectionImpl<K extends Json, V extends Json>
     return this.derive<K2, V2>(mapped);
   }
 
-  mapReduce<K2 extends Json, V2 extends Json, MapperParams extends Param[]>(
+  mapReduce<K2 extends Json, V2 extends Json, MapperParams extends DepSafe[]>(
     mapper: new (...params: MapperParams) => Mapper<K, V, K2, V2>,
     ...mapperParams: MapperParams
   ) {
-    return <Accum extends Json, ReducerParams extends Param[]>(
+    return <Accum extends Json, ReducerParams extends DepSafe[]>(
       reducer: new (...params: ReducerParams) => Reducer<V2, Accum>,
       ...reducerParams: ReducerParams
     ) => {
@@ -326,7 +277,7 @@ class EagerCollectionImpl<K extends Json, V extends Json>
       );
       const skreducer = this.refs.binding.SkipRuntime_createReducer(
         this.refs.handles.register(reducerObj),
-        this.refs.skjson.exportJSON(reducerObj.default),
+        this.refs.skjson.exportJSON(reducerObj.initial),
       );
       const mapped = this.refs.binding.SkipRuntime_Collection__mapReduce(
         this.collection,
@@ -337,7 +288,7 @@ class EagerCollectionImpl<K extends Json, V extends Json>
     };
   }
 
-  reduce<Accum extends Json, Params extends Param[]>(
+  reduce<Accum extends Json, Params extends DepSafe[]>(
     reducer: new (...params: Params) => Reducer<V, Accum>,
     ...params: Params
   ): EagerCollection<K, Accum> {
@@ -349,7 +300,7 @@ class EagerCollectionImpl<K extends Json, V extends Json>
     }
     const skreducer = this.refs.binding.SkipRuntime_createReducer(
       this.refs.handles.register(reducerObj),
-      this.refs.skjson.exportJSON(reducerObj.default),
+      this.refs.skjson.exportJSON(reducerObj.initial),
     );
     return this.derive<K, Accum>(
       this.refs.binding.SkipRuntime_Collection__reduce(
@@ -420,13 +371,17 @@ class CollectionWriter<K extends Json, V extends Json> {
   }
 }
 
-class ContextImpl extends SkFrozen implements Context {
+class ContextImpl extends SkManaged implements Context {
   constructor(private readonly refs: Refs) {
     super();
     Object.freeze(this);
   }
 
-  createLazyCollection<K extends Json, V extends Json, Params extends Param[]>(
+  createLazyCollection<
+    K extends Json,
+    V extends Json,
+    Params extends DepSafe[],
+  >(
     compute: new (...params: Params) => LazyCompute<K, V>,
     ...params: Params
   ): LazyCollection<K, V> {
@@ -447,7 +402,7 @@ class ContextImpl extends SkFrozen implements Context {
   useExternalResource<K extends Json, V extends Json>(resource: {
     service: string;
     identifier: string;
-    params?: { [param: string]: string | number };
+    params?: Json;
   }): EagerCollection<K, V> {
     const collection =
       this.refs.binding.SkipRuntime_Context__useExternalResource(
@@ -492,7 +447,7 @@ class AllChecker<K extends Json, V extends Json> implements Checker {
     private readonly service: ServiceInstance,
     private readonly executor: Executor<Entry<K, V>[]>,
     private readonly resource: string,
-    private readonly params: { [param: string]: string },
+    private readonly params: Json,
   ) {}
 
   check(request: string): void {
@@ -514,7 +469,7 @@ class OneChecker<K extends Json, V extends Json> implements Checker {
     private readonly service: ServiceInstance,
     private readonly executor: Executor<V[]>,
     private readonly resource: string,
-    private readonly params: { [param: string]: string },
+    private readonly params: Json,
     private readonly key: K,
   ) {}
 
@@ -533,6 +488,8 @@ class OneChecker<K extends Json, V extends Json> implements Checker {
   }
 }
 
+export type SubscriptionID = Opaque<bigint, "subscription">;
+
 /**
  * A `ServiceInstance` is a running instance of a `SkipService`, providing access to its resources
  * and operations to manage susbscriptions and the service itself.
@@ -549,7 +506,7 @@ export class ServiceInstance {
   instantiateResource(
     identifier: string,
     resource: string,
-    params: { [param: string]: string },
+    params: Json,
   ): void {
     const errorHdl = this.refs.runWithGC(() => {
       return this.refs.binding.SkipRuntime_Runtime__createResource(
@@ -569,7 +526,7 @@ export class ServiceInstance {
    */
   getAll<K extends Json, V extends Json>(
     resource: string,
-    params: { [param: string]: string } = {},
+    params: Json = {},
     request?: string | Executor<Entry<K, V>[]>,
   ): GetResult<Entry<K, V>[]> {
     const get_ = () => {
@@ -606,7 +563,7 @@ export class ServiceInstance {
   getArray<K extends Json, V extends Json>(
     resource: string,
     key: K,
-    params: { [param: string]: string } = {},
+    params: Json = {},
     request?: string | Executor<V[]>,
   ): GetResult<V[]> {
     const get_ = () => {
@@ -734,7 +691,7 @@ export class ServiceInstance {
   }
 }
 
-export class NonEmptyIteratorImpl<T> implements NonEmptyIterator<T> {
+class ValuesImpl<T> implements Values<T> {
   constructor(
     private readonly skjson: JsonConverter,
     private readonly binding: FromBinding,
@@ -745,26 +702,26 @@ export class NonEmptyIteratorImpl<T> implements NonEmptyIterator<T> {
     this.pointer = pointer;
   }
 
-  next(): Nullable<T & Param> {
+  next(): Nullable<T & DepSafe> {
     return this.skjson.importOptJSON(
       this.binding.SkipRuntime_NonEmptyIterator__next(this.pointer),
-    ) as Nullable<T & Param>;
+    ) as Nullable<T & DepSafe>;
   }
 
-  getUnique(): T & Param {
+  getUnique(): T & DepSafe {
     const value = this.skjson.importOptJSON(
       this.binding.SkipRuntime_NonEmptyIterator__uniqueValue(this.pointer),
-    ) as Nullable<T & Param>;
+    ) as Nullable<T & DepSafe>;
     if (value == null) throw new NonUniqueValueException();
     return value;
   }
 
-  toArray: () => (T & Param)[] = () => {
+  toArray: () => (T & DepSafe)[] = () => {
     return Array.from(this);
   };
 
-  [Symbol.iterator](): Iterator<T & Param> {
-    const cloned_iter = new NonEmptyIteratorImpl<T & Param>(
+  [Symbol.iterator](): Iterator<T & DepSafe> {
+    const cloned_iter = new ValuesImpl<T & DepSafe>(
       this.skjson,
       this.binding,
       this.binding.SkipRuntime_NonEmptyIterator__clone(this.pointer),
@@ -773,12 +730,12 @@ export class NonEmptyIteratorImpl<T> implements NonEmptyIterator<T> {
     return {
       next() {
         const value = cloned_iter.next();
-        return { value, done: value == null } as IteratorResult<T & Param>;
+        return { value, done: value == null } as IteratorResult<T & DepSafe>;
       },
     };
   }
 
-  map<U>(f: (value: T & Param, index: number) => U, thisObj?: any): U[] {
+  map<U>(f: (value: T & DepSafe, index: number) => U, thisObj?: any): U[] {
     return this.toArray().map(f, thisObj);
   }
 }
@@ -833,7 +790,7 @@ export class ToBinding {
     const mapper = this.handles.get(skmapper);
     const result = mapper.mapEntry(
       skjson.importJSON(key) as Json,
-      new NonEmptyIteratorImpl<Json>(skjson, this.binding, values),
+      new ValuesImpl<Json>(skjson, this.binding, values),
     );
     return skjson.exportJSON(Array.from(result) as [[Json, Json]]);
   }
@@ -851,11 +808,11 @@ export class ToBinding {
   ): Pointer<Internal.CJArray> {
     const skjson = this.getJsonConverter();
     const lazyCompute = this.handles.get(sklazyCompute);
-    const computed = lazyCompute.compute(
+    const result = lazyCompute.compute(
       new LazyCollectionImpl<Json, Json>(self, this.refs()),
       skjson.importJSON(skkey) as Json,
     );
-    return skjson.exportJSON(computed ? [computed] : []);
+    return skjson.exportJSON(Array.from(result));
   }
 
   SkipRuntime_deleteLazyCompute(lazyCompute: Handle<JSONLazyCompute>): void {
@@ -894,9 +851,7 @@ export class ToBinding {
   ): Pointer<Internal.Resource> {
     const skjson = this.getJsonConverter();
     const builder = this.handles.get(skbuilder);
-    const resource = builder.build(
-      skjson.importJSON(skparams) as { [param: string]: string },
-    );
+    const resource = builder.build(skjson.importJSON(skparams) as Json);
     return this.binding.SkipRuntime_createResource(
       this.handles.register(resource),
     );
@@ -987,7 +942,7 @@ export class ToBinding {
     return skjson.exportJSON(
       reducer.add(
         skacc ? (skjson.importJSON(skacc) as Json) : null,
-        skjson.importJSON(skvalue) as Json & Param,
+        skjson.importJSON(skvalue) as Json & DepSafe,
       ),
     );
   }
@@ -1002,7 +957,7 @@ export class ToBinding {
     return skjson.exportJSON(
       reducer.remove(
         skjson.importJSON(skacc) as Json,
-        skjson.importJSON(skvalue) as Json & Param,
+        skjson.importJSON(skvalue) as Json & DepSafe,
       ),
     );
   }
@@ -1022,9 +977,7 @@ export class ToBinding {
     const skjson = this.getJsonConverter();
     const supplier = this.handles.get(sksupplier);
     const writer = new CollectionWriter(writerId, this.refs());
-    const params = skjson.importJSON(skparams, true) as {
-      [param: string]: string;
-    };
+    const params = skjson.importJSON(skparams, true) as Json;
     supplier.subscribe(resource, params, {
       update: writer.update.bind(writer),
       error: writer.error.bind(writer),
@@ -1039,9 +992,7 @@ export class ToBinding {
   ): void {
     const skjson = this.getJsonConverter();
     const supplier = this.handles.get(sksupplier);
-    const params = skjson.importJSON(skparams, true) as {
-      [param: string]: string;
-    };
+    const params = skjson.importJSON(skparams, true) as Json;
     supplier.unsubscribe(resource, params);
   }
 

package/src/remote.ts

@@ -10,14 +10,29 @@ 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()}`;
@@ -31,7 +46,7 @@ export class SkipExternalService implements ExternalService {
 
   subscribe(
     resource: string,
-    params: { [param: string]: string },
+    params: Json,
     callbacks: {
       update: (updates: Entry<Json, Json>[], isInitial: boolean) => void;
       // FIXME: What is `error()` used for?
@@ -72,7 +87,7 @@ export class SkipExternalService implements ExternalService {
       });
   }
 
-  unsubscribe(resource: string, params: { [param: string]: string }) {
+  unsubscribe(resource: string, params: Json) {
     const closable = this.resources.get(this.toId(resource, params));
     if (closable) closable.close();
   }
@@ -83,12 +98,12 @@ export class SkipExternalService implements ExternalService {
     }
   }
 
-  private toId(resource: string, params: { [param: string]: string }): string {
-    // TODO: This is equivalent to `querystring.encode(params, ',', ':')`.
-    const strparams: string[] = [];
-    for (const key of Object.keys(params).sort()) {
-      strparams.push(`${key}:${params[key]}`);
-    }
-    return `${resource}[${strparams.join(",")}]`;
+  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))}]`;
   }
 }

package/src/utils.ts

@@ -1,48 +1,88 @@
 import type { Nullable } from "@skip-wasm/std";
 import { ManyToOneMapper } from "@skipruntime/api";
-import type { Reducer, NonEmptyIterator, Json } from "@skipruntime/api";
+import type { Reducer, Values, Json } from "@skipruntime/api";
 
+/**
+ * `Reducer` to maintain the sum of input values.
+ *
+ * A `Reducer` that maintains the sum of values as they are added and removed from a collection.
+ */
 export class Sum implements Reducer<number, number> {
-  default = 0;
+  initial = 0;
 
-  add(acc: number, value: number): number {
-    return acc + value;
+  add(accum: number, value: number): number {
+    return accum + value;
   }
 
-  remove(acc: number, value: number): Nullable<number> {
-    return acc - value;
+  remove(accum: number, value: number): Nullable<number> {
+    return accum - value;
   }
 }
 
+/**
+ * `Reducer` to maintain the minimum of input values.
+ *
+ * A `Reducer` that maintains the minimum of values as they are added and removed from a collection.
+ */
 export class Min implements Reducer<number, number> {
-  default = null;
+  initial = null;
 
-  add(acc: Nullable<number>, value: number): number {
-    return acc === null ? value : Math.min(acc, value);
+  add(accum: Nullable<number>, value: number): number {
+    return accum === null ? value : Math.min(accum, value);
   }
 
-  remove(acc: number, value: number): Nullable<number> {
-    return value > acc ? acc : null;
+  remove(accum: number, value: number): Nullable<number> {
+    return value > accum ? accum : null;
   }
 }
 
+/**
+ * `Reducer` to maintain the maximum of input values.
+ *
+ * A `Reducer` that maintains the maximum of values as they are added and removed from a collection.
+ */
 export class Max implements Reducer<number, number> {
-  default = null;
+  initial = null;
 
-  add(acc: Nullable<number>, value: number): number {
-    return acc === null ? value : Math.max(acc, value);
+  add(accum: Nullable<number>, value: number): number {
+    return accum === null ? value : Math.max(accum, value);
   }
 
-  remove(acc: number, value: number): Nullable<number> {
-    return value < acc ? acc : null;
+  remove(accum: number, value: number): Nullable<number> {
+    return value < accum ? accum : null;
   }
 }
 
+/**
+ * `Reducer` to maintain the count of input values.
+ *
+ * A `Reducer` that maintains the number of values as they are added and removed from a collection.
+ */
+export class Count<T extends Json> implements Reducer<T, number> {
+  initial = 0;
+
+  add(accum: number): number {
+    return accum + 1;
+  }
+
+  remove(accum: number): Nullable<number> {
+    return accum - 1;
+  }
+}
+
+/**
+ * `Mapper` to count input values.
+ *
+ * A `Mapper` that associates each key in the output with the number of values it is associated with in the input.
+ *
+ * @remarks
+ * If there are many values associated to keys in a collection, and they are updated frequently, using the `Count` `Reducer` instead could be more efficient.
+ */
 export class CountMapper<
   K extends Json,
   V extends Json,
 > extends ManyToOneMapper<K, V, number> {
-  mapValues(values: NonEmptyIterator<V>): number {
+  mapValues(values: Values<V>): number {
     return values.toArray().length;
   }
 }