@synnaxlabs/client 0.26.7 → 0.28.0

package/src/ontology/ontology.spec.ts

@@ -104,11 +104,9 @@ describe("Ontology", () => {
     });
     it("should correctly propagate resource changes to the ontology", async () => {
       const change = await client.ontology.openChangeTracker();
-      const p = new Promise<ontology.ResourceChange[]>((resolve) => {
-        change.resources.onChange((changes) => {
-          resolve(changes);
-        });
-      });
+      const p = new Promise<ontology.ResourceChange[]>((resolve) =>
+        change.resources.onChange((changes) => resolve(changes)),
+      );
       await client.ontology.groups.create(ontology.Root, randomName());
       const c = await p;
       expect(c.length).toBeGreaterThan(0);

package/src/ontology/payload.ts

@@ -17,7 +17,7 @@ export type RelationshipChange = change.Change<Relationship, undefined>;
 export type RelationshipSet = change.Set<Relationship, undefined>;
 export type RelationshipDelete = change.Delete<Relationship, undefined>;
 
-const resourceTypeZ = z.union([
+export const resourceTypeZ = z.union([
   z.literal("label"),
   z.literal("builtin"),
   z.literal("cluster"),
@@ -53,6 +53,8 @@ export const stringIDZ = z.string().transform((v) => {
 
 export const crudeIDZ = z.union([stringIDZ, idZ]);
 
+export type CrudeID = { type: ResourceType; key: string } | string;
+
 export class ID {
   type: ResourceType;
   key: string;
@@ -119,6 +121,8 @@ export type Resource<T extends UnknownRecord = UnknownRecord> = Omit<
   "data"
 > & { data?: T | null };
 
+export type RelationshipDirection = "from" | "to";
+
 export const relationshipSchemaZ = z.object({
   from: ID.z,
   type: z.string(),

package/src/ontology/writer.ts

@@ -10,7 +10,7 @@
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { type ID,idZ } from "@/ontology/payload";
+import { type CrudeID, ID, idZ } from "@/ontology/payload";
 
 const ENDPOINTS = {
   ADD_CHILDREN: "/ontology/add-children",
@@ -36,28 +36,42 @@ export class Writer {
     this.client = client;
   }
 
-  async addChildren(id: ID, ...children: ID[]): Promise<void> {
+  async addChildren(id: CrudeID, ...children: CrudeID[]): Promise<void> {
     await sendRequired<typeof addRemoveChildrenReqZ, z.ZodTypeAny>(
-      this.client, 
-      ENDPOINTS.ADD_CHILDREN, 
-      { id, children },
-      addRemoveChildrenReqZ, 
-      z.object({})
+      this.client,
+      ENDPOINTS.ADD_CHILDREN,
+      { id: new ID(id).payload, children: children.map((c) => new ID(c).payload) },
+      addRemoveChildrenReqZ,
+      z.object({}),
     );
   }
 
-  async removeChildren(id: ID, ...children: ID[]): Promise<void> {
+  async removeChildren(id: CrudeID, ...children: CrudeID[]): Promise<void> {
     await sendRequired<typeof addRemoveChildrenReqZ, z.ZodTypeAny>(
       this.client,
       ENDPOINTS.REMOVE_CHILDREN,
-      { id, children },
+      { id: new ID(id).payload, children: children.map((c) => new ID(c).payload) },
       addRemoveChildrenReqZ,
       z.object({}),
     );
   }
 
-  async moveChildren(from: ID, to: ID, ...children: ID[]): Promise<void> {
-    const req = { from, to, children };
-    await sendRequired(this.client, ENDPOINTS.MOVE_CHILDREN, req, moveChildrenReqZ, z.object({}));
+  async moveChildren(
+    from: CrudeID,
+    to: CrudeID,
+    ...children: CrudeID[]
+  ): Promise<void> {
+    const req = {
+      from: new ID(from).payload,
+      to: new ID(to).payload,
+      children: children.map((c) => new ID(c).payload),
+    };
+    await sendRequired(
+      this.client,
+      ENDPOINTS.MOVE_CHILDREN,
+      req,
+      moveChildrenReqZ,
+      z.object({}),
+    );
   }
 }

package/src/ranger/client.ts

@@ -8,17 +8,22 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { CrudeTimeRange, TimeRange } from "@synnaxlabs/x";
+import { CrudeTimeRange, observe, TimeRange } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
+import { type Series } from "@synnaxlabs/x/telem";
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
+import { Key as ChannelKey } from "@/channel/payload";
 import { type Retriever as ChannelRetriever } from "@/channel/retriever";
 import { MultipleFoundError, NotFoundError } from "@/errors";
+import { QueryError } from "@/errors";
 import { type framer } from "@/framer";
 import { type label } from "@/label";
-import { Active } from "@/ranger/active";
-import { Aliaser } from "@/ranger/alias";
+import { type Label } from "@/label/payload";
+import { ontology } from "@/ontology";
+import { Resource } from "@/ontology/payload";
+import { type Alias, Aliaser } from "@/ranger/alias";
 import { KV } from "@/ranger/kv";
 import {
   analyzeParams,
@@ -32,16 +37,170 @@ import {
   type Payload,
   payloadZ,
 } from "@/ranger/payload";
-import { Range } from "@/ranger/range";
-import { type Writer } from "@/ranger/writer";
+import { CreateOptions, type Writer } from "@/ranger/writer";
 import { signals } from "@/signals";
 import { nullableArrayZ } from "@/util/zod";
 
+const ontologyID = (key: string): ontology.ID =>
+  new ontology.ID({ type: "range", key });
+
+export class Range {
+  key: string;
+  name: string;
+  readonly kv: KV;
+  readonly timeRange: TimeRange;
+  readonly color: string | undefined;
+  readonly channels: ChannelRetriever;
+  private readonly aliaser: Aliaser;
+  private readonly frameClient: framer.Client;
+  private readonly labelClient: label.Client;
+  private readonly ontologyClient: ontology.Client;
+  private readonly rangeClient: Client;
+
+  constructor(
+    name: string,
+    timeRange: TimeRange = TimeRange.ZERO,
+    key: string,
+    color: string | undefined,
+    _frameClient: framer.Client,
+    _kv: KV,
+    _aliaser: Aliaser,
+    _channels: ChannelRetriever,
+    _labelClient: label.Client,
+    _ontologyClient: ontology.Client,
+    _rangeClient: Client,
+  ) {
+    this.key = key;
+    this.name = name;
+    this.timeRange = timeRange;
+    this.frameClient = _frameClient;
+    this.color = color;
+    this.kv = _kv;
+    this.aliaser = _aliaser;
+    this.channels = _channels;
+    this.labelClient = _labelClient;
+    this.ontologyClient = _ontologyClient;
+    this.rangeClient = _rangeClient;
+  }
+
+  get ontologyID(): ontology.ID {
+    return new ontology.ID({ key: this.key, type: "range" });
+  }
+
+  get payload(): Payload {
+    return {
+      key: this.key,
+      name: this.name,
+      timeRange: this.timeRange,
+      color: this.color,
+    };
+  }
+
+  async setAlias(channel: ChannelKey | Name, alias: string): Promise<void> {
+    const ch = await this.channels.retrieve(channel);
+    if (ch.length === 0) {
+      throw new QueryError(`Channel ${channel} does not exist`);
+    }
+    await this.aliaser.set({ [ch[0].key]: alias });
+  }
+
+  async deleteAlias(...channels: ChannelKey[]): Promise<void> {
+    await this.aliaser.delete(channels);
+  }
+
+  async listAliases(): Promise<Record<ChannelKey, string>> {
+    return await this.aliaser.list();
+  }
+
+  async resolveAlias(alias: string): Promise<ChannelKey> {
+    return await this.aliaser.resolve(alias);
+  }
+
+  async openAliasTracker(): Promise<signals.Observable<string, Alias>> {
+    return await this.aliaser.openChangeTracker();
+  }
+
+  async retrieveParent(): Promise<Range | null> {
+    return this.rangeClient.retrieveParent(this.key);
+  }
+
+  async retrieveChildren(): Promise<Range[]> {
+    const res = (
+      await this.ontologyClient.retrieveChildren(this.ontologyID, {
+        excludeFieldData: true,
+        types: ["range"],
+      })
+    ).map((r) => r.id.key);
+    return await this.rangeClient.retrieve(res);
+  }
+
+  async read(channel: Key | Name): Promise<Series>;
+
+  async read(channels: Params): Promise<framer.Frame>;
+
+  async read(channels: Params): Promise<Series | framer.Frame> {
+    return await this.frameClient.read(this.timeRange, channels);
+  }
+
+  async labels(): Promise<Label[]> {
+    return await this.labelClient.retrieveFor(ontologyID(this.key));
+  }
+
+  async addLabel(...labels: label.Key[]): Promise<void> {
+    await this.labelClient.label(ontologyID(this.key), labels);
+  }
+
+  async removeLabel(...labels: label.Key[]): Promise<void> {
+    await this.labelClient.removeLabels(ontologyID(this.key), labels);
+  }
+
+  async openChildRangeTracker(): Promise<observe.ObservableAsyncCloseable<Range[]>> {
+    const wrapper = new observe.Observer<Range[]>();
+    const initial: ontology.Resource[] = (await this.retrieveChildren()).map((r) => {
+      const id = new ontology.ID({ key: r.key, type: "range" });
+      return { id, key: id.toString(), name: r.name, data: r.payload };
+    });
+    const base = await this.ontologyClient.openDependentTracker({
+      target: this.ontologyID,
+      dependents: initial,
+      resourceType: "range",
+    });
+    base.onChange((r: Resource[]) =>
+      wrapper.notify(this.rangeClient.resourcesToRanges(r)),
+    );
+    wrapper.setCloser(async () => await base.close());
+    return wrapper;
+  }
+
+  async openParentRangeTracker(): Promise<observe.ObservableAsyncCloseable<Range> | null> {
+    const wrapper = new observe.Observer<Range>();
+    const p = await this.retrieveParent();
+    if (p == null) return null;
+    const id = new ontology.ID({ key: p.key, type: "range" });
+    const resourceP = { id, key: id.toString(), name: p.name, data: p.payload };
+    const base = await this.ontologyClient.openDependentTracker({
+      target: this.ontologyID,
+      dependents: [resourceP],
+      relationshipDirection: "to",
+    });
+    base.onChange((resources: Resource[]) => {
+      const ranges = this.rangeClient.resourcesToRanges(resources);
+      if (ranges.length === 0) return;
+      const p = ranges[0];
+      wrapper.notify(p);
+    });
+    wrapper.setCloser(async () => await base.close());
+    return wrapper;
+  }
+}
+
 const retrieveReqZ = z.object({
   keys: keyZ.array().optional(),
   names: z.array(z.string()).optional(),
   term: z.string().optional(),
   overlapsWith: TimeRange.z.optional(),
+  limit: z.number().int().optional(),
+  offset: z.number().int().optional(),
 });
 
 export type RetrieveRequest = z.infer<typeof retrieveReqZ>;
@@ -58,8 +217,8 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
   private readonly writer: Writer;
   private readonly unaryClient: UnaryClient;
   private readonly channels: ChannelRetriever;
-  private readonly active: Active;
   private readonly labelClient: label.Client;
+  private readonly ontologyClient: ontology.Client;
 
   constructor(
     frameClient: framer.Client,
@@ -67,22 +226,26 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
     unary: UnaryClient,
     channels: ChannelRetriever,
     labelClient: label.Client,
+    ontologyClient: ontology.Client,
   ) {
     this.frameClient = frameClient;
     this.writer = writer;
     this.unaryClient = unary;
     this.channels = channels;
-    this.active = new Active(unary);
     this.labelClient = labelClient;
+    this.ontologyClient = ontologyClient;
   }
 
-  async create(range: NewPayload): Promise<Range>;
+  async create(range: NewPayload, options?: CreateOptions): Promise<Range>;
 
-  async create(ranges: NewPayload[]): Promise<Range[]>;
+  async create(ranges: NewPayload[], options?: CreateOptions): Promise<Range[]>;
 
-  async create(ranges: NewPayload | NewPayload[]): Promise<Range | Range[]> {
+  async create(
+    ranges: NewPayload | NewPayload[],
+    options?: CreateOptions,
+  ): Promise<Range | Range[]> {
     const single = !Array.isArray(ranges);
-    const res = this.sugar(await this.writer.create(toArray(ranges)));
+    const res = this.sugarMany(await this.writer.create(toArray(ranges), options));
     return single ? res[0] : res;
   }
 
@@ -95,11 +258,11 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
   }
 
   async search(term: string): Promise<Range[]> {
-    return this.sugar(await this.execRetrieve({ term }));
+    return this.sugarMany(await this.execRetrieve({ term }));
   }
 
-  async page(): Promise<Range[]> {
-    return [];
+  async page(offset: number, limit: number): Promise<Range[]> {
+    return this.sugarMany(await this.execRetrieve({ offset, limit }));
   }
 
   async retrieve(range: CrudeTimeRange): Promise<Range[]>;
@@ -111,7 +274,8 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
   async retrieve(params: Params | CrudeTimeRange): Promise<Range | Range[]> {
     if (typeof params === "object" && "start" in params)
       return await this.execRetrieve({ overlapsWith: new TimeRange(params) });
-    const { single, actual, variant, normalized } = analyzeParams(params);
+    const { single, actual, variant, normalized, empty } = analyzeParams(params);
+    if (empty) return [];
     const ranges = await this.execRetrieve({ [variant]: normalized });
     if (!single) return ranges;
     if (ranges.length === 0)
@@ -121,6 +285,10 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
     return ranges[0];
   }
 
+  getKV(range: Key): KV {
+    return new KV(range, this.unaryClient, this.frameClient);
+  }
+
   private async execRetrieve(req: RetrieveRequest): Promise<Range[]> {
     const { ranges } = await sendRequired<typeof retrieveReqZ, typeof retrieveResZ>(
       this.unaryClient,
@@ -129,37 +297,38 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
       retrieveReqZ,
       retrieveResZ,
     );
-    return this.sugar(ranges);
+    return this.sugarMany(ranges);
   }
 
-  async setActive(range: Key): Promise<void> {
-    await this.active.setActive(range);
-  }
-
-  async retrieveActive(): Promise<Range | null> {
-    const res = await this.active.retrieveActive();
-    if (res == null) return null;
-    return this.sugar([res])[0];
+  async retrieveParent(range: Key): Promise<Range | null> {
+    const res = await this.ontologyClient.retrieveParents({
+      key: range,
+      type: "range",
+    });
+    if (res.length === 0) return null;
+    const first = res[0];
+    if (first.id.type !== "range") return null;
+    return await this.retrieve(first.id.key);
   }
 
-  async clearActive(range: Key): Promise<void> {
-    await this.active.clearActive(range);
+  sugarOne(payload: Payload): Range {
+    return new Range(
+      payload.name,
+      payload.timeRange,
+      payload.key,
+      payload.color,
+      this.frameClient,
+      new KV(payload.key, this.unaryClient, this.frameClient),
+      new Aliaser(payload.key, this.frameClient, this.unaryClient),
+      this.channels,
+      this.labelClient,
+      this.ontologyClient,
+      this,
+    );
   }
 
-  private sugar(payloads: Payload[]): Range[] {
-    return payloads.map((payload) => {
-      return new Range(
-        payload.name,
-        payload.timeRange,
-        payload.key,
-        payload.color,
-        this.frameClient,
-        new KV(payload.key, this.unaryClient),
-        new Aliaser(payload.key, this.frameClient, this.unaryClient),
-        this.channels,
-        this.labelClient,
-      );
-    });
+  sugarMany(payloads: Payload[]): Range[] {
+    return payloads.map((payload) => this.sugarOne(payload));
   }
 
   async openTracker(): Promise<signals.Observable<string, Range>> {
@@ -170,9 +339,22 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
       (variant, data) => {
         if (variant === "delete")
           return data.toStrings().map((k) => ({ variant, key: k, value: undefined }));
-        const sugared = this.sugar(data.parseJSON(payloadZ));
+        const sugared = this.sugarMany(data.parseJSON(payloadZ));
         return sugared.map((r) => ({ variant, key: r.key, value: r }));
       },
     );
   }
+
+  resourcesToRanges(resources: Resource[]): Range[] {
+    return resources.map((r) => this.resourceToRange(r));
+  }
+
+  resourceToRange(resource: Resource): Range {
+    return this.sugarOne({
+      key: resource.id.key,
+      name: resource.data?.name as string,
+      timeRange: new TimeRange(resource.data?.timeRange as CrudeTimeRange),
+      color: resource.data?.color as string,
+    });
+  }
 }

package/src/ranger/external.ts

@@ -9,6 +9,6 @@
 
 export type { Alias, AliasChange } from "@/ranger/alias";
 export * from "@/ranger/client";
+export * from "@/ranger/kv";
 export * from "@/ranger/payload";
-export * from "@/ranger/range";
 export * from "@/ranger/writer";

package/src/ranger/kv.ts

@@ -7,27 +7,36 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { sendRequired,type UnaryClient } from "@synnaxlabs/freighter";
+import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { isObject } from "@synnaxlabs/x/identity";
 import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
+import { framer } from "@/framer";
 import { type Key, keyZ } from "@/ranger/payload";
+import { signals } from "@/signals";
+import { nullableArrayZ } from "@/util/zod";
 
 const getReqZ = z.object({
   range: keyZ,
   keys: z.string().array(),
 });
 
+const kvPairZ = z.object({
+  range: keyZ,
+  key: z.string(),
+  value: z.string(),
+});
+
 const getResZ = z.object({
-  pairs: z.record(z.string(), z.string()),
+  pairs: nullableArrayZ(kvPairZ),
 });
 
 export type GetRequest = z.infer<typeof getReqZ>;
 
 const setReqZ = z.object({
   range: keyZ,
-  pairs: z.record(z.string(), z.string()),
+  pairs: kvPairZ.array(),
 });
 
 export type SetRequest = z.infer<typeof setReqZ>;
@@ -39,16 +48,20 @@ const deleteReqZ = z.object({
 
 export type DeleteRequest = z.infer<typeof deleteReqZ>;
 
+export type KVPair = z.infer<typeof kvPairZ>;
+
 export class KV {
   private static readonly GET_ENDPOINT = "/range/kv/get";
   private static readonly SET_ENDPOINT = "/range/kv/set";
   private static readonly DELETE_ENDPOINT = "/range/kv/delete";
   private readonly rangeKey: Key;
   private readonly client: UnaryClient;
+  private readonly frameClient: framer.Client;
 
-  constructor(rng: Key, client: UnaryClient) {
+  constructor(rng: Key, client: UnaryClient, frameClient: framer.Client) {
     this.rangeKey = rng;
     this.client = client;
+    this.frameClient = frameClient;
   }
 
   async get(key: string): Promise<string>;
@@ -56,14 +69,15 @@ export class KV {
   async get(keys: string[]): Promise<Record<string, string>>;
 
   async get(keys: string | string[]): Promise<string | Record<string, string>> {
-    const [res, err] = await this.client.send(
+    const res = await sendRequired(
+      this.client,
       KV.GET_ENDPOINT,
       { range: this.rangeKey, keys: toArray(keys) },
       getReqZ,
       getResZ,
     );
-    if (err != null) throw err;
-    return Array.isArray(keys) ? res.pairs : res.pairs[keys];
+    if (typeof keys === "string") return res.pairs[0].value;
+    return Object.fromEntries(res.pairs.map((pair) => [pair.key, pair.value]));
   }
 
   async list(): Promise<Record<string, string>> {
@@ -75,13 +89,18 @@ export class KV {
   async set(kv: Record<string, string>): Promise<void>;
 
   async set(key: string | Record<string, string>, value: string = ""): Promise<void> {
+    let pairs: KVPair[];
+    if (isObject(key))
+      pairs = Object.entries(key).map(([k, v]) => ({
+        range: this.rangeKey,
+        key: k,
+        value: v,
+      }));
+    else pairs = [{ range: this.rangeKey, key: key, value: value }];
     await sendRequired(
       this.client,
       KV.SET_ENDPOINT,
-      {
-        range: this.rangeKey,
-        pairs: isObject(key) ? key : { [key]: value },
-      },
+      { range: this.rangeKey, pairs },
       setReqZ,
       z.unknown(),
     );
@@ -96,4 +115,24 @@ export class KV {
       z.unknown(),
     );
   }
+
+  async openTracker(): Promise<signals.Observable<string, KVPair>> {
+    return await signals.openObservable<string, KVPair>(
+      this.frameClient,
+      "sy_range_kv_set",
+      "sy_range_kv_delete",
+      (variant, data) => {
+        if (variant === "delete")
+          return data.toStrings().map((combinedKey) => {
+            const [range, key] = combinedKey.split("<--->", 2);
+            return { variant, key: combinedKey, value: { range, key, value: "" } };
+          });
+        return data.parseJSON(kvPairZ).map((pair) => ({
+          variant,
+          key: `${pair.range}${pair.key}`,
+          value: pair,
+        }));
+      },
+    );
+  }
 }

package/src/ranger/payload.ts

@@ -31,7 +31,7 @@ export type Payload = z.infer<typeof payloadZ>;
 export const newPayloadZ = payloadZ.extend({
   key: z.string().uuid().optional(),
 });
-export type NewPayload = z.infer<typeof newPayloadZ>;
+export type NewPayload = z.input<typeof newPayloadZ>;
 
 export type ParamAnalysisResult =
   | {
@@ -39,37 +39,41 @@ export type ParamAnalysisResult =
       variant: "keys";
       normalized: Keys;
       actual: Key;
+      empty: never;
     }
   | {
       single: true;
       variant: "names";
       normalized: Names;
       actual: Name;
+      empty: never;
     }
   | {
       single: false;
       variant: "keys";
       normalized: Keys;
       actual: Keys;
+      empty: boolean;
     }
   | {
       single: false;
       variant: "names";
       normalized: Names;
       actual: Names;
+      empty: boolean;
     };
 
 export const analyzeParams = (params: Params): ParamAnalysisResult => {
   const normal = toArray(params) as Keys | Names;
-  if (normal.length === 0) {
-    throw new Error("Range params must not be empty");
-  }
-  const isKey = keyZ.safeParse(normal[0]).success;
+  const empty = normal.length === 0;
+  let isKey = false;
+  if (!empty) isKey = keyZ.safeParse(normal[0]).success;
   return {
     single: !Array.isArray(params),
     variant: isKey ? "keys" : "names",
     normalized: normal,
     actual: params,
+    empty,
   } as const as ParamAnalysisResult;
 };