@synnaxlabs/client 0.56.2 → 0.57.1

package/src/transport.ts

@@ -8,28 +8,39 @@
 // included in the file licenses/APL.txt.
 
 import {
+  type FileTransport,
   HTTPClient,
   type Middleware,
   type UnaryClient,
   unaryWithBreaker,
   WebSocketClient,
 } from "@synnaxlabs/freighter";
-import { binary, type breaker, type URL } from "@synnaxlabs/x";
+import { binary, type breaker, type url } from "@synnaxlabs/x";
 
 export class Transport {
-  readonly url: URL;
+  readonly url: url.URL;
   readonly unary: UnaryClient;
+  /**
+   * The unary client without the breaker's retry wrapper, for callers that own their
+   * retry policy (the connection checker). Shares middleware with {@link unary}.
+   */
+  readonly unaryNoRetry: UnaryClient;
+  readonly file: FileTransport;
   readonly stream: WebSocketClient;
   readonly secure: boolean;
 
-  constructor(url: URL, breakerCfg: breaker.Config = {}, secure: boolean = false) {
+  constructor(url: url.URL, breakerCfg: breaker.Config = {}, secure: boolean = false) {
     this.secure = secure;
     this.url = url.child("/api/v1/");
     const codec = new binary.JSONCodec();
-    this.unary = unaryWithBreaker(
-      new HTTPClient(this.url, codec, this.secure),
-      breakerCfg,
-    );
+    // The streaming file client and the unary client share one HTTPClient, so
+    // middleware (e.g. auth) registered through unary applies to file too. The file
+    // client deliberately skips the breaker's retry wrapper: an upload body may be a
+    // one-shot ReadableStream that cannot be re-sent on a retry.
+    const http = new HTTPClient(this.url, codec, this.secure);
+    this.unary = unaryWithBreaker(http, breakerCfg);
+    this.unaryNoRetry = http;
+    this.file = http;
     this.stream = new WebSocketClient(this.url, codec, this.secure);
   }
 

package/src/user/client.ts

@@ -8,17 +8,19 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import { array, primitive, record } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { MultipleFoundError, NotFoundError } from "@/errors";
 import { ontology } from "@/ontology";
+import { query } from "@/query";
 import { type Key, keyZ, type New, newZ, type User, userZ } from "@/user/types.gen";
 
 const retrieveRequestZ = z.object({
   keys: keyZ.array().optional(),
   usernames: z.string().array().optional(),
 });
+const retrieveMultiParamsZ = retrieveRequestZ.or(query.keyListZ(keyZ));
 
 const keyRetrieveRequestZ = z
   .object({
@@ -32,28 +34,21 @@ const usernameRetrieveRequestZ = z
   })
   .transform(({ username }) => ({ usernames: [username] }));
 
-const usernamesRetrieveRequestZ = z
-  .object({
-    usernames: z.string().array(),
-  })
-  .transform(({ usernames }) => ({ usernames }));
-
 export type KeyRetrieveRequest = z.input<typeof keyRetrieveRequestZ>;
 export type UsernameRetrieveRequest = z.input<typeof usernameRetrieveRequestZ>;
-export type UsernamesRetrieveRequest = z.input<typeof usernamesRetrieveRequestZ>;
+export type UsernamesRetrieveRequest = { usernames: string[] };
 
-const retrieveArgsZ = z.union([
+const retrieveParamsZ = z.union([
   keyRetrieveRequestZ,
   usernameRetrieveRequestZ,
-  usernamesRetrieveRequestZ,
   retrieveRequestZ,
 ]);
 
-export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+export type RetrieveParams = z.input<typeof retrieveParamsZ>;
 
 export interface RetrieveRequest extends z.infer<typeof retrieveRequestZ> {}
 
-const retrieveResZ = z.object({ users: array.nullishToEmpty(userZ) });
+const retrieveResZ = z.object({ users: userZ.array().default(() => []) });
 
 const createReqZ = z.object({ users: newZ.array() });
 const createResZ = z.object({ users: userZ.array() });
@@ -71,82 +66,188 @@ const deleteResZ = z.object({});
 export const SET_CHANNEL_NAME = "sy_user_set";
 export const DELETE_CHANNEL_NAME = "sy_user_delete";
 
-export class Client {
-  private readonly client: UnaryClient;
+type SingleParams = KeyRetrieveRequest | UsernameRetrieveRequest;
+
+const singleParamsZ = z.union([
+  z.strictObject({ key: keyZ }),
+  z.strictObject({ username: z.string() }),
+  keyZ.transform((key) => ({ key })),
+]);
 
-  constructor(client: UnaryClient) {
-    this.client = client;
+const singleIdentifier = (params: SingleParams): string =>
+  "key" in params ? `key ${params.key}` : `username ${params.username}`;
+
+const requestFilter = (req: RetrieveRequest): ((u: User) => boolean) => {
+  const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+  const usernameSet = primitive.isNonZero(req.usernames)
+    ? new Set(req.usernames)
+    : undefined;
+  return (u) => {
+    if (keySet != null && !keySet.has(u.key)) return false;
+    if (usernameSet != null && !usernameSet.has(u.username)) return false;
+    return true;
+  };
+};
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  cache: query.Cache;
+  ontology: ontology.Client;
+}
+
+export class Client extends query.Retriever<
+  typeof retrieveMultiParamsZ,
+  Key,
+  User,
+  User,
+  SingleParams,
+  SingleParams
+> {
+  private readonly cfg: ClientConfig;
+  private readonly store: query.Table<Key, User>;
+
+  constructor(cfg: ClientConfig) {
+    const { cache } = cfg;
+    const store = cache.createTable<Key, User>({
+      name: "users",
+      fetch: async (keys) => await this.execRetrieve({ keys }),
+    });
+    const single = cache.queries<SingleParams, User, Key, User>({
+      name: "user",
+      table: store,
+      fetch: async (params) => {
+        if (!("key" in params)) {
+          const [cached] = store.get((u) => u.username === params.username);
+          if (cached != null) return [cached.key];
+        }
+        const users = await this.execRetrieve(params);
+        checkSingle(params, users);
+        store.ingest(users);
+        return users.map((u) => u.key);
+      },
+      compose: (records) => records[0],
+      keyOf: (params) => ("key" in params ? params.key : null),
+      matches: (u, params) =>
+        "key" in params ? u.key === params.key : u.username === params.username,
+      single: true,
+    });
+    super(cache, {
+      name: "user",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.execRetrieve(req),
+        matches: (u, req) => requestFilter(req)(u),
+      },
+      single: { schema: singleParamsZ, space: single },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
   async create(user: New): Promise<User>;
   async create(users: New[]): Promise<User[]>;
   async create(users: New | New[]): Promise<User | User[]> {
     const isMany = Array.isArray(users);
-    const res = await this.client.send(
+    const res = await this.cfg.unary.send(
       "/user/create",
       { users: array.toArray(users) },
       createReqZ,
       createResZ,
     );
+    this.store.set(res.users);
     return isMany ? res.users : res.users[0];
   }
 
-  async changeUsername(key: Key, newUsername: string): Promise<void> {
-    await this.client.send(
-      "/user/change-username",
-      { key, username: newUsername },
-      changeUsernameReqZ,
-      changeUsernameResZ,
-    );
+  async changeUsername(
+    key: Key,
+    newUsername: string,
+    opts: query.WriteOptions = {},
+  ): Promise<void> {
+    const update = () => [
+      query.partialUpdate(this.store, key, { username: newUsername }),
+      this.cfg.ontology.cache.renameResource(ontologyID(key), newUsername),
+    ];
+    await query.optimistic({
+      rollbacks: update(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/user/change-username",
+          { key, username: newUsername },
+          changeUsernameReqZ,
+          changeUsernameResZ,
+        ),
+    });
+    update();
   }
 
-  async retrieve(args: KeyRetrieveRequest): Promise<User>;
-  async retrieve(args: UsernameRetrieveRequest): Promise<User>;
-  async retrieve(args: RetrieveArgs): Promise<User[]>;
-  async retrieve(args: RetrieveArgs): Promise<User | User[]> {
-    const isSingle = "key" in args || "username" in args;
-    const res = await this.client.send(
-      "/user/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResZ,
-    );
-
-    if (!isSingle) return res.users;
-
-    if (res.users.length === 0) {
-      const identifier =
-        "key" in args ? `key ${args.key}` : `username ${args.username}`;
-      throw new NotFoundError(`No user with ${identifier} found`);
-    }
-    if (res.users.length > 1) {
-      const identifier =
-        "key" in args ? `key ${args.key}` : `username ${args.username}`;
-      throw new MultipleFoundError(`Multiple users found with ${identifier}`);
-    }
-    return res.users[0];
+  async rename(
+    key: Key,
+    firstName?: string,
+    lastName?: string,
+    opts: query.WriteOptions = {},
+  ): Promise<void> {
+    await query.optimistic({
+      rollbacks: [
+        query.partialUpdate(
+          this.store,
+          key,
+          record.purgeUndefined({ firstName, lastName }),
+        ),
+      ],
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/user/rename",
+          { key, firstName, lastName },
+          renameReqZ,
+          renameResZ,
+        ),
+    });
   }
 
-  async rename(key: Key, firstName?: string, lastName?: string): Promise<void> {
-    await this.client.send(
-      "/user/rename",
-      { key, firstName, lastName },
-      renameReqZ,
-      renameResZ,
-    );
+  async delete(key: Key, opts?: query.WriteOptions): Promise<void>;
+  async delete(keys: Key[], opts?: query.WriteOptions): Promise<void>;
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => [
+      this.cfg.ontology.cache.deleteResources(ontologyID(keysArr)),
+      this.store.delete(keysArr),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/user/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          deleteResZ,
+        ),
+    });
+    drop();
   }
 
-  async delete(key: Key): Promise<void>;
-  async delete(keys: Key[]): Promise<void>;
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/user/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      deleteResZ,
+  private async execRetrieve(params: RetrieveParams): Promise<User[]> {
+    const res = await this.cfg.unary.send(
+      "/user/retrieve",
+      params,
+      retrieveParamsZ,
+      retrieveResZ,
     );
+    return res.users;
   }
 }
 
+const checkSingle = (params: SingleParams, users: User[]): void => {
+  if (users.length === 0)
+    throw new NotFoundError(`No user with ${singleIdentifier(params)} found`);
+  if (users.length > 1)
+    throw new MultipleFoundError(
+      `Multiple users found with ${singleIdentifier(params)}`,
+    );
+};
+
 export const ontologyID = ontology.createIDFactory<Key>("user");
 export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/user/external.ts

@@ -12,7 +12,7 @@ export {
   DELETE_CHANNEL_NAME,
   type KeyRetrieveRequest,
   ontologyID,
-  type RetrieveArgs,
+  type RetrieveParams,
   type RetrieveRequest,
   SET_CHANNEL_NAME,
   TYPE_ONTOLOGY_ID,

package/src/user/types.gen.ts

@@ -17,21 +17,21 @@ export const keyZ = z.uuid();
 export type Key = z.infer<typeof keyZ>;
 
 /**
- * User is an account entity representing a person accessing the Synnax system.
- * Users can have roles assigned for permission management.
+ * User is an account entity representing a person accessing the Synnax system. Users
+ * can have roles assigned for permission management.
  */
 export const userZ = z.object({
   /** key is the unique identifier for this user. */
   key: keyZ,
   /** username is the unique login name for the user. */
-  username: z.string().min(1, "Username is required"),
+  username: z.string().min(1, "username is required"),
   /** firstName is the user's first name. */
   firstName: z.string(),
   /** lastName is the user's last name. */
   lastName: z.string(),
   /**
-   * rootUser is true if this is a root/admin user with full system access. Root
-   * users cannot be deleted.
+   * rootUser is true if this is a root/admin user with full system access. Root users
+   * cannot be deleted.
    */
   rootUser: z.boolean().default(false),
 });

package/src/util/retrieve.ts

@@ -15,14 +15,14 @@ export type SingleParamAnalysisResult<
   T extends primitive.Value,
   K extends PartialTypeNameRecord<T>,
 > = T extends unknown
-  ? { single: true; variant: K[keyof K]; normalized: T[]; actual: T }
+  ? { single: true; variant: K[TypeName<T>]; normalized: T[]; actual: T }
   : never;
 
 export type MultiParamAnalysisResult<
   T extends primitive.Value,
   K extends PartialTypeNameRecord<T>,
 > = T extends unknown
-  ? { single: false; variant: K[keyof K]; normalized: T[]; actual: T[] }
+  ? { single: false; variant: K[TypeName<T>]; normalized: T[]; actual: T[] }
   : never;
 
 type TypeName<T> = T extends string
@@ -62,10 +62,10 @@ export const analyzeParams = <
   let normal = array.toArray(args);
   const first = normal[0];
   const t = typeof first;
-  let variant: K[keyof K];
+  let variant: K[TypeName<T>];
   if (t === "string" && convertNumericStrings)
     if (!isNaN(parseInt(first as string, 10)) && "number" in variantMap) {
-      variant = variantMap.number as K[keyof K];
+      variant = variantMap.number as K[TypeName<T>];
       normal = normal.map((n) => parseInt(n as string, 10));
     } else variant = variantMap[t as TypeName<T>];
   else variant = variantMap[t as TypeName<T>];

package/src/util/telem.ts

@@ -10,7 +10,6 @@
 import { type DataType, type TypedArray } from "@synnaxlabs/x";
 
 export const randomSeries = (length: number, dataType: DataType): TypedArray => {
-  // create random bytes of the correct length
   const bytes = new Uint8Array(length * dataType.density.valueOf());
   for (let i = 0; i < bytes.byteLength; i++) bytes[i] = Math.floor(Math.random() * 256);
   return new dataType.Array(bytes.buffer);

package/src/view/client.ts

@@ -8,16 +8,24 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import { array, type destructor, primitive } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { checkForMultipleOrNoResults } from "@/util/retrieve";
-import { type Key, keyZ, type New, newZ, type View, viewZ } from "@/view/types.gen";
+import { ontology } from "@/ontology";
+import { query } from "@/query";
+import {
+  type Key,
+  keyZ,
+  type New,
+  ontologyID,
+  type View,
+  viewZ,
+} from "@/view/types.gen";
 
 export const SET_CHANNEL_NAME = "sy_view_set";
 export const DELETE_CHANNEL_NAME = "sy_view_delete";
 
-const createReqZ = z.object({ views: newZ.array() });
+const createReqZ = z.object({ views: viewZ.array() });
 const createResZ = z.object({ views: viewZ.array() });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 const emptyResZ = z.object({});
@@ -29,60 +37,135 @@ const retrieveRequestZ = z.object({
   offset: z.number().optional(),
   limit: z.number().optional(),
 });
+const retrieveMultiParamsZ = retrieveRequestZ.or(query.keyListZ(keyZ));
 
-const singleRetrieveArgsZ = z
-  .object({ key: keyZ })
-  .transform(({ key }) => ({ keys: [key] }));
+export type RetrieveSingleParams = { key: Key };
+export interface RetrieveMultipleParams extends z.input<typeof retrieveRequestZ> {}
 
-const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveRequestZ]);
+interface RetrieveRequest extends z.infer<typeof retrieveRequestZ> {}
 
-export interface RetrieveSingleParams extends z.input<typeof singleRetrieveArgsZ> {}
-export interface RetrieveMultipleParams extends z.input<typeof retrieveRequestZ> {}
+const retrieveResponseZ = z.object({ views: viewZ.array().default(() => []) });
 
-const retrieveResponseZ = z.object({ views: array.nullishToEmpty(viewZ) });
+/**
+ * Client-side matching for a request: key and type sets. Server-computed
+ * shapes (search, limit/offset) never reach this filter; they refetch instead.
+ */
+const requestFilter = (req: RetrieveRequest): ((v: View) => boolean) => {
+  const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+  const typeSet = primitive.isNonZero(req.types) ? new Set(req.types) : undefined;
+  return (v) => {
+    if (keySet != null && !keySet.has(v.key)) return false;
+    if (typeSet != null && !typeSet.has(v.type)) return false;
+    return true;
+  };
+};
 
-export class Client {
-  private readonly client: UnaryClient;
+export interface ClientConfig {
+  unary: UnaryClient;
+  cache: query.Cache;
+  ontology: ontology.Client;
+}
 
-  constructor(client: UnaryClient) {
-    this.client = client;
-  }
+export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, View> {
+  private readonly cfg: ClientConfig;
+  private readonly store: query.Table<Key, View>;
 
-  async retrieve(args: RetrieveSingleParams): Promise<View>;
-  async retrieve(args: RetrieveMultipleParams): Promise<View[]>;
-  async retrieve(
-    args: RetrieveSingleParams | RetrieveMultipleParams,
-  ): Promise<View | View[]> {
-    const isSingle = "key" in args;
-    const res = await this.client.send(
-      "/view/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResponseZ,
-    );
-    checkForMultipleOrNoResults("View", args, res.views, isSingle);
-    return isSingle ? res.views[0] : res.views;
+  constructor(cfg: ClientConfig) {
+    const { cache } = cfg;
+    const store = cache.createTable<Key, View>({
+      name: "views",
+      fetch: async (keys) => await this.execRetrieve({ keys }),
+      listen: [
+        query.createSetListener(SET_CHANNEL_NAME, viewZ),
+        query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ),
+      ],
+    });
+    super(cache, {
+      name: "view",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.execRetrieve(req),
+        matches: (view, req) => requestFilter(req)(view),
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
   async create(view: New): Promise<View>;
   async create(views: New[]): Promise<View[]>;
   async create(views: New | New[]): Promise<View | View[]> {
     const isMany = Array.isArray(views);
-    const res = await this.client.send(
+    const res = await this.cfg.unary.send(
       "/view/create",
       { views: array.toArray(views) },
       createReqZ,
       createResZ,
     );
+    this.store.set(res.views);
     return isMany ? res.views : res.views[0];
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/view/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      emptyResZ,
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const v = await this.retrieve(key);
+    const rename = () => [
+      query.partialUpdate(this.store, key, { name }),
+      this.cfg.ontology.cache.renameResource(ontologyID(key), name),
+    ];
+    await query.optimistic({
+      rollbacks: rename(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () => {
+        await this.create({ ...v, name });
+      },
+    });
+    rename();
+  }
+
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const ids = ontologyID(keysArr);
+    const drop = () => [
+      this.cfg.ontology.cache.deleteRelationships(ids),
+      this.store.delete(keysArr),
+      this.cfg.ontology.cache.resources.delete(ontology.idToString(ids)),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/view/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
+  }
+
+  /** Subscribes to every view set delivered to the cache. */
+  onSet(handler: (view: View) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "set") handler(event.value);
+    });
+  }
+
+  /** Subscribes to every view delete delivered to the cache. */
+  onDelete(handler: (key: Key) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "delete") handler(event.key);
+    });
+  }
+
+  private async execRetrieve(params: RetrieveMultipleParams): Promise<View[]> {
+    const res = await this.cfg.unary.send(
+      "/view/retrieve",
+      params,
+      retrieveRequestZ,
+      retrieveResponseZ,
     );
+    return res.views;
   }
 }

package/src/view/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { record } from "@synnaxlabs/x";
+import { record, uuid } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
@@ -18,27 +18,24 @@ export const keyZ = z.uuid();
 export type Key = z.infer<typeof keyZ>;
 
 /**
- * View is a persisted view configuration storing visualization settings and
- * query parameters for line plots, tables, schematics, and other view
- * types.
+ * View is a persisted view configuration storing visualization settings and query
+ * parameters for line plots, tables, schematics, and other view types.
  */
 export const viewZ = z.object({
   /** key is the unique identifier for this view. */
-  key: keyZ,
+  key: keyZ.default(uuid.create),
   /** name is a human-readable name for the view. */
   name: z.string(),
   /** type is the view type identifier (e.g., 'lineplot', 'table', 'schematic'). */
   type: z.string(),
   /**
-   * query is a type-agnostic JSON object containing view-specific configuration
-   * and query parameters.
+   * query is a type-agnostic JSON object containing view-specific configuration and
+   * query parameters.
    */
-  query: record.nullishToEmpty(),
+  query: record.unknownZ().default(() => ({})),
 });
 export interface View extends z.infer<typeof viewZ> {}
-
-export const newZ = viewZ.partial({ key: true });
-export interface New extends z.input<typeof newZ> {}
+export interface New extends z.input<typeof viewZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("view");
 export const TYPE_ONTOLOGY_ID = ontologyID("");