@synnaxlabs/client 0.26.1 → 0.27.0

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,169 @@ 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,
+      })
+    ).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(
+      this.ontologyID,
+      initial,
+    );
+    base.onChange((resources: Resource[]) =>
+      wrapper.notify(this.rangeClient.resourcesToRanges(resources)),
+    );
+    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(
+      this.ontologyID,
+      [resourceP],
+      "parent",
+      "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 +216,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 +225,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.sugar(await this.writer.create(toArray(ranges), options));
     return single ? res[0] : res;
   }
 
@@ -98,8 +260,8 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
     return this.sugar(await this.execRetrieve({ term }));
   }
 
-  async page(): Promise<Range[]> {
-    return [];
+  async page(offset: number, limit: number): Promise<Range[]> {
+    return this.sugar(await this.execRetrieve({ offset, limit }));
   }
 
   async retrieve(range: CrudeTimeRange): Promise<Range[]>;
@@ -111,7 +273,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 +284,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,
@@ -132,21 +299,18 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
     return this.sugar(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 clearActive(range: Key): Promise<void> {
-    await this.active.clearActive(range);
+  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);
   }
 
-  private sugar(payloads: Payload[]): Range[] {
+  sugar(payloads: Payload[]): Range[] {
     return payloads.map((payload) => {
       return new Range(
         payload.name,
@@ -154,10 +318,12 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
         payload.key,
         payload.color,
         this.frameClient,
-        new KV(payload.key, this.unaryClient),
+        new KV(payload.key, this.unaryClient, this.frameClient),
         new Aliaser(payload.key, this.frameClient, this.unaryClient),
         this.channels,
         this.labelClient,
+        this.ontologyClient,
+        this,
       );
     });
   }
@@ -175,4 +341,14 @@ export class Client implements AsyncTermSearcher<string, Key, Range> {
       },
     );
   }
+
+  resourcesToRanges(resources: Resource[]): Range[] {
+    return this.sugar(
+      resources.map((r) => ({
+        key: r.id.key,
+        name: r.data?.name as string,
+        timeRange: new TimeRange(r.data?.timeRange as CrudeTimeRange),
+      })),
+    );
+  }
 }

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;
 };