@synnaxlabs/client 0.2.1 → 0.13.6

package/src/ontology/retriever.ts

@@ -0,0 +1,91 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import type { UnaryClient } from "@synnaxlabs/freighter";
+import { toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { ID, type Resource, idZ, resourceSchemaZ } from "@/ontology/payload";
+
+const requestSchema = z.object({
+  ids: idZ.array().optional(),
+  children: z.boolean().optional(),
+  parents: z.boolean().optional(),
+  includeSchema: z.boolean().optional(),
+  includeFieldData: z.boolean().optional(),
+  term: z.string().optional(),
+});
+
+type Request = z.infer<typeof requestSchema>;
+
+const responseSchema = z.object({
+  resources: resourceSchemaZ.array(),
+});
+
+export class Retriever {
+  private static readonly ENDPOINT = "/ontology/retrieve";
+  private readonly client: UnaryClient;
+
+  constructor(unary: UnaryClient) {
+    this.client = unary;
+  }
+
+  async search(term: string): Promise<Resource[]> {
+    const resources = await this.execute({ term });
+    return resources;
+  }
+
+  async retrieve(
+    ids: ID | ID[] | string | string[],
+    includeSchema: boolean = true,
+    includeFieldData: boolean = true,
+  ): Promise<Resource[]> {
+    return await this.execute({
+      ids: toArray(ids).map((id) => new ID(id).payload),
+      includeFieldData,
+      includeSchema,
+    });
+  }
+
+  async retrieveChildren(
+    ids: ID | ID[],
+    includeSchema: boolean = true,
+    includeFieldData: boolean = true,
+  ): Promise<Resource[]> {
+    return await this.execute({
+      ids: toArray(ids).map((id) => new ID(id).payload),
+      children: true,
+      includeSchema,
+      includeFieldData,
+    });
+  }
+
+  async retrieveParents(
+    ids: ID | ID[],
+    includeSchema: boolean = true,
+    includeFieldData: boolean = true,
+  ): Promise<Resource[]> {
+    return await this.execute({
+      ids: toArray(ids).map((id) => new ID(id).payload),
+      parents: true,
+      includeSchema,
+      includeFieldData,
+    });
+  }
+
+  private async execute(request: Request): Promise<Resource[]> {
+    const [res, err] = await this.client.send(
+      Retriever.ENDPOINT,
+      request,
+      responseSchema,
+    );
+    if (err != null) throw err;
+    return res.resources;
+  }
+}

package/src/ontology/signals.ts

@@ -0,0 +1,135 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { observe, type change } from "@synnaxlabs/x";
+
+import { QueryError } from "@/errors";
+import { type Client as FrameClient } from "@/framer/client";
+import { type Frame } from "@/framer/frame";
+import { type Streamer as FrameStreamer } from "@/framer/streamer";
+import {
+  ID,
+  parseRelationship,
+  type Relationship,
+  type Resource,
+} from "@/ontology/payload";
+import { type Retriever } from "@/ontology/retriever";
+
+export type ResourceChange = change.Change<ID, Resource>;
+export type RelationshipChange = change.Change<Relationship, undefined>;
+
+const RESOURCE_SET_NAME = "sy_ontology_resource_set";
+const RESOURCE_DELETE_NAME = "sy_ontology_resource_delete";
+const RELATIONSHIP_SET_NAME = "sy_ontology_relationship_set";
+const RELATIONSHIP_DELETE_NAME = "sy_ontology_relationship_delete";
+
+export class ChangeTracker {
+  private readonly resourceObs: observe.Observer<ResourceChange[]>;
+  private readonly relationshipObs: observe.Observer<RelationshipChange[]>;
+
+  readonly relationships: observe.Observable<RelationshipChange[]>;
+  readonly resources: observe.Observable<ResourceChange[]>;
+
+  private readonly streamer: FrameStreamer;
+  private readonly retriever: Retriever;
+  private readonly closePromise: Promise<void>;
+
+  constructor(streamer: FrameStreamer, retriever: Retriever) {
+    this.relationshipObs = new observe.Observer<RelationshipChange[]>();
+    this.relationships = this.relationshipObs;
+    this.resourceObs = new observe.Observer<ResourceChange[]>();
+    this.resources = this.resourceObs;
+    this.retriever = retriever;
+    this.streamer = streamer;
+    this.closePromise = this.start();
+  }
+
+  async close(): Promise<void> {
+    this.streamer.close();
+    await this.closePromise;
+  }
+
+  private async start(): Promise<void> {
+    for await (const frame of this.streamer) {
+      await this.update(frame);
+    }
+  }
+
+  private async update(frame: Frame): Promise<void> {
+    const resSets = await this.parseResourceSets(frame);
+    const resDeletes = this.parseResourceDeletes(frame);
+    const allResources = resSets.concat(resDeletes);
+    if (allResources.length > 0) this.resourceObs.notify(resSets.concat(resDeletes));
+    const relSets = this.parseRelationshipSets(frame);
+    const relDeletes = this.parseRelationshipDeletes(frame);
+    const allRels = relSets.concat(relDeletes);
+    if (allRels.length > 0) this.relationshipObs.notify(relSets.concat(relDeletes));
+  }
+
+  private parseRelationshipSets(frame: Frame): RelationshipChange[] {
+    const relationships = frame.get(RELATIONSHIP_SET_NAME);
+    if (relationships.length === 0) return [];
+    // We should only ever get one series of relationships
+    return relationships[0].toStrings().map((rel) => ({
+      variant: "set",
+      key: parseRelationship(rel),
+      value: undefined,
+    }));
+  }
+
+  private parseRelationshipDeletes(frame: Frame): RelationshipChange[] {
+    const relationships = frame.get(RELATIONSHIP_DELETE_NAME);
+    if (relationships.length === 0) return [];
+    // We should only ever get one series of relationships
+    return relationships[0].toStrings().map((rel) => ({
+      variant: "delete",
+      key: parseRelationship(rel),
+    }));
+  }
+
+  private async parseResourceSets(frame: Frame): Promise<ResourceChange[]> {
+    const sets = frame.get(RESOURCE_SET_NAME);
+    if (sets.length === 0) return [];
+    // We should only ever get one series of sets
+    const ids = sets[0].toStrings().map((id) => new ID(id));
+    try {
+      const resources = await this.retriever.retrieve(ids);
+      return resources.map((resource) => ({
+        variant: "set",
+        key: resource.id,
+        value: resource,
+      }));
+    } catch (e) {
+      if (e instanceof QueryError) {
+        console.warn(e);
+        return [];
+      }
+      throw e;
+    }
+  }
+
+  private parseResourceDeletes(frame: Frame): ResourceChange[] {
+    const deletes = frame.get(RESOURCE_DELETE_NAME);
+    if (deletes.length === 0) return [];
+    // We should only ever get one series of deletes
+    return deletes[0]
+      .toStrings()
+      .map((str) => ({ variant: "delete", key: new ID(str) }));
+  }
+
+  static async open(client: FrameClient, retriever: Retriever): Promise<ChangeTracker> {
+    const streamer = await client.newStreamer([
+      RESOURCE_SET_NAME,
+      RESOURCE_DELETE_NAME,
+      RELATIONSHIP_SET_NAME,
+      RELATIONSHIP_DELETE_NAME,
+    ]);
+    return new ChangeTracker(streamer, retriever);
+  }
+}

package/src/ontology/writer.ts

@@ -0,0 +1,49 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { z } from "zod";
+
+import { type ID } from "@/ontology/payload";
+
+const ENDPOINTS = {
+  ADD_CHILDREN: "/ontology/add-children",
+  REMOVE_CHILDREN: "/ontology/remove-children",
+  MOVE_CHILDREN: "/ontology/move-children",
+};
+
+export class Writer {
+  client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async addChildren(id: ID, ...children: ID[]): Promise<void> {
+    const req = { id, children };
+    const [, err] = await this.client.send(ENDPOINTS.ADD_CHILDREN, req, z.object({}));
+    if (err != null) throw err;
+  }
+
+  async removeChildren(id: ID, ...children: ID[]): Promise<void> {
+    const req = { id, children };
+    const [, err] = await this.client.send(
+      ENDPOINTS.REMOVE_CHILDREN,
+      req,
+      z.object({}),
+    );
+    if (err != null) throw err;
+  }
+
+  async moveChildren(from: ID, to: ID, ...children: ID[]): Promise<void> {
+    const req = { from, to, children };
+    const [, err] = await this.client.send(ENDPOINTS.MOVE_CHILDREN, req, z.object({}));
+    if (err != null) throw err;
+  }
+}

package/src/ranger/active.ts

@@ -0,0 +1,56 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { z } from "zod";
+
+import { QueryError } from "..";
+
+import { type Payload, payloadZ, type Key } from "./payload";
+
+const setActiveResZ = z.object({});
+
+const retrieveActiveResZ = z.object({
+  range: payloadZ,
+});
+
+const clearActiveResZ = z.object({});
+
+const SET_ENDPOINT = "/range/set-active";
+const RETRIEVE_ENDPOINT = "/range/retrieve-active";
+const CLEAR_ENDPOINT = "/range/clear-active";
+
+export class Active {
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async setActive(range: Key): Promise<void> {
+    const [, err] = await this.client.send(SET_ENDPOINT, { range }, setActiveResZ);
+    if (err != null) throw err;
+  }
+
+  async retrieveActive(): Promise<Payload | null> {
+    const [res, err] = await this.client.send(
+      RETRIEVE_ENDPOINT,
+      {},
+      retrieveActiveResZ,
+    );
+    if (err instanceof QueryError) return null;
+    if (err != null) throw err;
+    return res.range;
+  }
+
+  async clearActive(range: Key): Promise<void> {
+    const [, err] = await this.client.send(CLEAR_ENDPOINT, { range }, clearActiveResZ);
+    if (err != null) throw err;
+  }
+}

package/src/ranger/alias.ts

@@ -0,0 +1,183 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// 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 { type change } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type channel } from "@/channel";
+import { keyZ as channelKeyZ, type Key as ChannelKey } from "@/channel/payload";
+import { type Client as FrameClient } from "@/framer/client";
+import { type Key, keyZ } from "@/ranger/payload";
+import { signals } from "@/signals";
+
+export const ALIAS_SET_NAME = "sy_range_alias_set";
+export const ALIAS_DELETE_NAME = "sy_range_alias_delete";
+
+const resolveReqZ = z.object({
+  range: keyZ,
+  aliases: z.string().array(),
+});
+
+const resolveResZ = z.object({
+  aliases: z.record(z.string(), channelKeyZ),
+});
+
+const setReqZ = z.object({
+  range: keyZ,
+  aliases: z.record(channelKeyZ, z.string()),
+});
+
+const setResZ = z.unknown();
+
+const deleteReqZ = z.object({
+  range: keyZ,
+  channels: channelKeyZ.array(),
+});
+
+const deleteResZ = z.unknown();
+
+const listReqZ = z.object({
+  range: keyZ,
+});
+
+const listResZ = z.object({
+  aliases: z.record(z.string(), z.string()),
+});
+
+export class Aliaser {
+  private static readonly SET_ENDPOINT = "/range/alias/set";
+  private static readonly RESOLVE_ENDPOINT = "/range/alias/resolve";
+  private static readonly LIST_ENDPOINT = "/range/alias/list";
+  private static readonly DELETE_ENDPOINT = "/range/alias/delete";
+  private readonly frameClient: FrameClient;
+  private readonly cache = new Map<string, ChannelKey>();
+  private readonly client: UnaryClient;
+  private readonly rangeKey: Key;
+
+  constructor(rangeKey: Key, frameClient: FrameClient, client: UnaryClient) {
+    this.rangeKey = rangeKey;
+    this.cache = new Map();
+    this.client = client;
+    this.frameClient = frameClient;
+  }
+
+  resolve(aliases: string): Promise<ChannelKey>;
+
+  resolve(aliases: string[]): Promise<Record<string, ChannelKey>>;
+
+  async resolve(
+    aliases: string | string[],
+  ): Promise<ChannelKey | Record<string, ChannelKey>> {
+    const toFetch: string[] = [];
+    const isSingle = typeof aliases === "string";
+    const cached: Record<string, ChannelKey> = {};
+    if (isSingle) {
+      const c = this.cache.get(aliases);
+      if (c != null) return c;
+      toFetch.push(aliases);
+    } else
+      aliases.forEach((alias) => {
+        const c = this.cache.get(alias);
+        if (c != null) cached[alias] = c;
+        else toFetch.push(alias);
+      });
+    if (toFetch.length === 0) return cached;
+    const res = await sendRequired<typeof resolveReqZ, typeof resolveResZ>(
+      this.client,
+      Aliaser.RESOLVE_ENDPOINT,
+      { range: this.rangeKey, aliases: toFetch },
+      resolveResZ,
+    );
+    Object.entries(res.aliases).forEach(([alias, key]) => this.cache.set(alias, key));
+    return isSingle ? res.aliases[toFetch[0]] : { ...cached, ...res.aliases };
+  }
+
+  async set(aliases: Record<ChannelKey, string>): Promise<void> {
+    await sendRequired<typeof setReqZ, typeof setResZ>(
+      this.client,
+      Aliaser.SET_ENDPOINT,
+      {
+        range: this.rangeKey,
+        aliases,
+      },
+      z.unknown(),
+    );
+  }
+
+  async list(): Promise<Record<ChannelKey, string>> {
+    return (
+      await sendRequired<typeof listReqZ, typeof listResZ>(
+        this.client,
+        Aliaser.LIST_ENDPOINT,
+        {
+          range: this.rangeKey,
+        },
+        listResZ,
+      )
+    ).aliases;
+  }
+
+  async delete(aliases: ChannelKey[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
+      this.client,
+      Aliaser.DELETE_ENDPOINT,
+      {
+        range: this.rangeKey,
+        channels: aliases,
+      },
+      deleteResZ,
+    );
+  }
+
+  async openChangeTracker(): Promise<signals.Observable<string, Alias>> {
+    return await signals.Observable.open<string, Alias>(
+      this.frameClient,
+      ALIAS_SET_NAME,
+      ALIAS_DELETE_NAME,
+      decodeAliasChanges(this.rangeKey),
+    );
+  }
+}
+
+export interface Alias {
+  range: Key;
+  channel: channel.Key;
+  alias: string;
+}
+
+export type AliasChange = change.Change<string, Alias>;
+
+const aliasZ = z.object({
+  range: keyZ,
+  channel: channelKeyZ,
+  alias: z.string(),
+});
+
+const aliasSeparator = "---";
+
+const decodeAliasChanges =
+  (rangeKey: Key): signals.Decoder<string, Alias> =>
+  (variant, data) => {
+    if (variant === "delete") {
+      return data
+        .toStrings()
+        .filter((k) => k.split(aliasSeparator)[0] === rangeKey)
+        .map((alias) => ({
+          variant,
+          key: alias,
+          value: undefined,
+        }));
+    }
+    return data.parseJSON(aliasZ).map((alias) => ({
+      variant,
+      key: alias.alias,
+      value: alias,
+    }));
+  };

package/src/ranger/client.ts

@@ -0,0 +1,129 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { type UnaryClient } from "@synnaxlabs/freighter";
+import { type AsyncTermSearcher, toArray } from "@synnaxlabs/x";
+
+import { type Retriever as ChannelRetriever } from "@/channel/retriever";
+import { QueryError } from "@/errors";
+import { type framer } from "@/framer";
+import { type label } from "@/label";
+import { type ontology } from "@/ontology";
+import { Active } from "@/ranger/active";
+import { Aliaser } from "@/ranger/alias";
+import { KV } from "@/ranger/kv";
+import {
+  type NewPayload,
+  type Key,
+  type Keys,
+  type Name,
+  type Names,
+  type Params,
+  type Payload,
+  analyzeParams,
+} from "@/ranger/payload";
+import { Range } from "@/ranger/range";
+import { type Retriever } from "@/ranger/retriever";
+import { type Writer } from "@/ranger/writer";
+
+export class Client implements AsyncTermSearcher<string, Key, Range> {
+  private readonly frameClient: framer.Client;
+  private readonly retriever: Retriever;
+  private readonly writer: Writer;
+  private readonly unaryClient: UnaryClient;
+  private readonly channels: ChannelRetriever;
+  private readonly active: Active;
+  private readonly labelClient: label.Client;
+
+  constructor(
+    frameClient: framer.Client,
+    retriever: Retriever,
+    writer: Writer,
+    unary: UnaryClient,
+    channels: ChannelRetriever,
+    labelClient: label.Client,
+  ) {
+    this.frameClient = frameClient;
+    this.retriever = retriever;
+    this.writer = writer;
+    this.unaryClient = unary;
+    this.channels = channels;
+    this.active = new Active(unary);
+    this.labelClient = labelClient;
+  }
+
+  async create(range: NewPayload): Promise<Range>;
+
+  async create(ranges: NewPayload[]): Promise<Range[]>;
+
+  async create(ranges: NewPayload | NewPayload[]): Promise<Range | Range[]> {
+    const single = !Array.isArray(ranges);
+    const res = this.sugar(await this.writer.create(toArray(ranges)));
+    return single ? res[0] : res;
+  }
+
+  async rename(key: Key, name: Name): Promise<void> {
+    await this.writer.rename(key, name);
+  }
+
+  async delete(key: Key | Keys): Promise<void> {
+    await this.writer.delete(toArray(key));
+  }
+
+  async search(term: string): Promise<Range[]> {
+    return this.sugar(await this.retriever.search(term));
+  }
+
+  async page(offset: number, limit: number): Promise<Range[]> {
+    return [];
+  }
+
+  async retrieve(range: Key | Name): Promise<Range>;
+
+  async retrieve(params: Keys | Names): Promise<Range[]>;
+
+  async retrieve(params: Params): Promise<Range | Range[]> {
+    const { single, actual } = analyzeParams(params);
+    const res = this.sugar(await this.retriever.retrieve(params));
+    if (!single) return res;
+    if (res.length === 0) throw new QueryError(`range matching ${actual} not found`);
+    if (res.length > 1)
+      throw new QueryError(`multiple ranges matching ${actual} found`);
+    return res[0];
+  }
+
+  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);
+  }
+
+  private sugar(payloads: Payload[]): Range[] {
+    return payloads.map((payload) => {
+      return new Range(
+        payload.name,
+        payload.timeRange,
+        payload.key,
+        this.frameClient,
+        new KV(payload.key, this.unaryClient),
+        new Aliaser(payload.key, this.frameClient, this.unaryClient),
+        this.channels,
+        this.labelClient,
+      );
+    });
+  }
+}

package/src/ranger/external.ts

@@ -0,0 +1,15 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * from "@/ranger/client";
+export * from "@/ranger/writer";
+export * from "@/ranger/payload";
+export * from "@/ranger/range";
+export * from "@/ranger/retriever";
+export type { Alias, AliasChange } from "@/ranger/alias";

package/src/ranger/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * as ranger from "@/ranger/external";