@synnaxlabs/client 0.2.0 → 0.13.5

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 { cdc } from "@/cdc";
+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";
+
+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<cdc.Observable<string, Alias>> {
+    return await cdc.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): cdc.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,124 @@
+// 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 { 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";
+
+import { Active } from "./active";
+
+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;
+
+  constructor(
+    frameClient: framer.Client,
+    retriever: Retriever,
+    writer: Writer,
+    unary: UnaryClient,
+    channels: ChannelRetriever,
+  ) {
+    this.frameClient = frameClient;
+    this.retriever = retriever;
+    this.writer = writer;
+    this.unaryClient = unary;
+    this.channels = channels;
+    this.active = new Active(unary);
+  }
+
+  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,
+      );
+    });
+  }
+}

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

package/src/ranger/kv.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, sendRequired } from "@synnaxlabs/freighter";
+import { isObject, toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Key, keyZ } from "@/ranger/payload";
+
+const getReqZ = z.object({
+  range: keyZ,
+  keys: z.string().array(),
+});
+
+const getResZ = z.object({
+  pairs: z.record(z.string(), z.string()),
+});
+
+export type GetRequest = z.infer<typeof getReqZ>;
+
+const setReqZ = z.object({
+  range: keyZ,
+  pairs: z.record(z.string(), z.string()),
+});
+
+export type SetRequest = z.infer<typeof setReqZ>;
+
+const deleteReqZ = z.object({
+  range: keyZ,
+  keys: z.string().array(),
+});
+
+export type DeleteRequest = z.infer<typeof deleteReqZ>;
+
+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;
+
+  constructor(rng: Key, client: UnaryClient) {
+    this.rangeKey = rng;
+    this.client = client;
+  }
+
+  async get(key: string): Promise<string>;
+
+  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(
+      KV.GET_ENDPOINT,
+      { range: this.rangeKey, keys: toArray(keys) },
+      getResZ,
+    );
+    if (err != null) throw err;
+    return Array.isArray(keys) ? res.pairs : res.pairs[keys];
+  }
+
+  async set(key: string, value: string): Promise<void>;
+
+  async set(kv: Record<string, string>): Promise<void>;
+
+  async set(key: string | Record<string, string>, value?: string): Promise<void> {
+    await sendRequired(
+      this.client,
+      KV.SET_ENDPOINT,
+      {
+        range: this.rangeKey,
+        pairs: isObject(key) ? key : { [key]: value },
+      },
+      z.unknown(),
+    );
+  }
+
+  async delete(key: string | string[]): Promise<void> {
+    await sendRequired(
+      this.client,
+      KV.DELETE_ENDPOINT,
+      { range: this.rangeKey, keys: toArray(key) },
+      z.unknown(),
+    );
+  }
+}

package/src/ranger/payload.ts

@@ -0,0 +1,70 @@
+// 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 { TimeRange, toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+export const keyZ = z.string().uuid();
+export type Key = z.infer<typeof keyZ>;
+export type Name = string;
+export type Keys = Key[];
+export type Names = Name[];
+export type Params = Key | Name | Keys | Names;
+
+export const payloadZ = z.object({
+  key: keyZ,
+  name: z.string(),
+  timeRange: TimeRange.z,
+});
+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 ParamAnalsysisResult =
+  | {
+      single: true;
+      variant: "keys";
+      normalized: Keys;
+      actual: Key;
+    }
+  | {
+      single: true;
+      variant: "names";
+      normalized: Names;
+      actual: Name;
+    }
+  | {
+      single: false;
+      variant: "keys";
+      normalized: Keys;
+      actual: Keys;
+    }
+  | {
+      single: false;
+      variant: "names";
+      normalized: Names;
+      actual: Names;
+    };
+
+export const analyzeParams = (params: Params): ParamAnalsysisResult => {
+  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;
+  return {
+    single: !Array.isArray(params),
+    variant: isKey ? "keys" : "names",
+    normalized: normal,
+    actual: params,
+  } as const as ParamAnalsysisResult;
+};

package/src/ranger/range.ts

@@ -0,0 +1,74 @@
+// 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 Series, TimeRange } from "@synnaxlabs/x";
+
+import { type cdc } from "@/cdc";
+import { type Key, type Params, type Name } from "@/channel/payload";
+import { type Retriever as ChannelRetriever } from "@/channel/retriever";
+import { QueryError } from "@/errors";
+import { type framer } from "@/framer";
+import { type Alias, type Aliaser } from "@/ranger/alias";
+import { type KV } from "@/ranger/kv";
+
+export class Range {
+  key: string;
+  name: string;
+  readonly kv: KV;
+  readonly timeRange: TimeRange;
+  readonly channels: ChannelRetriever;
+  private readonly aliaser: Aliaser;
+  private readonly frameClient: framer.Client;
+
+  constructor(
+    name: string,
+    timeRange: TimeRange = TimeRange.ZERO,
+    key: string,
+    _frameClient: framer.Client,
+    _kv: KV,
+    _aliaser: Aliaser,
+    _channels: ChannelRetriever,
+  ) {
+    this.key = key;
+    this.name = name;
+    this.timeRange = timeRange;
+    this.frameClient = _frameClient;
+    this.kv = _kv;
+    this.aliaser = _aliaser;
+    this.channels = _channels;
+  }
+
+  async setAlias(channel: Key | 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: Key[]): Promise<void> {
+    await this.aliaser.delete(channels);
+  }
+
+  async listAliases(): Promise<Record<Key, string>> {
+    return await this.aliaser.list();
+  }
+
+  async openAliasTracker(): Promise<cdc.Observable<string, Alias>> {
+    return await this.aliaser.openChangeTracker();
+  }
+
+  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);
+  }
+}