@synnaxlabs/client 0.56.1 → 0.57.0

package/src/status/client.ts

@@ -8,12 +8,14 @@
 // 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 { label } from "@/label";
 import { ontology } from "@/ontology";
-import { type Key, keyZ, type New, newZ, type Status, statusZ } from "@/status/payload";
+import { query } from "@/query";
+import { DELETE_CHANNEL_NAME, ontologyID, SET_CHANNEL_NAME } from "@/status/payload";
+import { type Key, keyZ, type New, type Status, statusZ } from "@/status/types.gen";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
 const setReqZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
@@ -21,11 +23,11 @@ const setReqZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
 ) =>
   z.object({
     parent: ontology.idZ.optional(),
-    statuses: newZ(detailsSchema).array(),
+    statuses: statusZ({ details: detailsSchema }).array(),
   });
 const setResZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
   detailsSchema?: DetailsSchema,
-) => z.object({ statuses: statusZ(detailsSchema).array() });
+) => z.object({ statuses: statusZ({ details: detailsSchema }).array() });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 const emptyResZ = z.object({});
 
@@ -37,52 +39,139 @@ const retrieveRequestZ = z.object({
   includeLabels: z.boolean().optional(),
   hasLabels: label.keyZ.array().optional(),
   variants: z.string().array().optional(),
+  ignoreNotFoundError: z.boolean().optional(),
 });
+const retrieveMultiParamsZ = retrieveRequestZ.or(query.keyListZ(keyZ));
 
-const singleRetrieveArgsZ = z
+const singleRetrieveParamsZ = z
   .object({ key: keyZ, includeLabels: z.boolean().optional() })
   .transform(({ key, includeLabels }) => ({ keys: [key], includeLabels }));
 
-const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveRequestZ]);
+const retrieveParamsZ = z.union([singleRetrieveParamsZ, retrieveRequestZ]);
 
-export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
-export type SingleRetrieveArgs = z.input<typeof singleRetrieveArgsZ>;
-export type MultiRetrieveArgs = z.input<typeof retrieveRequestZ>;
+export type RetrieveParams = z.input<typeof retrieveParamsZ>;
+export type SingleRetrieveParams = z.input<typeof singleRetrieveParamsZ>;
+export type MultiRetrieveParams = z.input<typeof retrieveRequestZ>;
+
+interface RetrieveRequest extends z.infer<typeof retrieveRequestZ> {}
 
 const retrieveResponseZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
   detailsSchema?: DetailsSchema,
-) => z.object({ statuses: array.nullishToEmpty(statusZ(detailsSchema)) });
+) =>
+  z.object({
+    statuses: statusZ({ details: detailsSchema })
+      .array()
+      .default(() => []),
+  });
 
-export interface SetOptions {
+export interface SetOptions extends query.WriteOptions {
   parent?: ontology.ID;
 }
 
-export class Client {
+const BASE_REQUEST: Partial<RetrieveRequest> = { includeLabels: true };
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  cache: query.Cache;
+  ontology: ontology.Client;
+  labels: label.Client;
+}
+
+export class Client extends query.Retriever<
+  typeof retrieveMultiParamsZ,
+  Key,
+  Status,
+  Status,
+  SingleRetrieveParams
+> {
   readonly type: string = "status";
-  private readonly client: UnaryClient;
+  readonly store: query.Table<Key, Status>;
+  private readonly cfg: ClientConfig;
 
-  constructor(client: UnaryClient) {
-    this.client = client;
+  constructor(cfg: ClientConfig) {
+    const { cache, ontology: ontologyClient, labels } = cfg;
+    const { relationships } = ontologyClient.cache;
+    const store = cache.createTable<Key, Status>({
+      name: "statuses",
+      fetch: async (keys) => await this.fetchThrough({ keys }),
+      listen: [
+        query.createSetListener(SET_CHANNEL_NAME, statusZ(), {
+          value: (changed, prev) => {
+            const next = { ...prev, ...changed };
+            const id = ontologyID(changed.key);
+            next.labels = label.cachedLabelsOf(relationships, labels.store, id);
+            return next;
+          },
+        }),
+        query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ),
+      ],
+    });
+    const composed = cache.derive<Key, Status, Status>({
+      name: "status.composed",
+      source: store,
+      compose: (record) => this.compose(record),
+      watch: [
+        query.deriveWatch(relationships, (event) => this.affectedKeys(event)),
+        query.deriveWatch(labels.store, (event) => this.statusesLabeledBy(event.key)),
+      ],
+    });
+    const single = cache.queries<Key, Status, Key, Status>({
+      name: "status",
+      table: composed,
+      fetch: async (key) => [(await this.fetchSingle(key)).key],
+      compose: (records) => records[0],
+      keyOf: (key) => key,
+      single: true,
+    });
+    super(cache, {
+      name: "status",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.fetchThrough(req),
+        matches: (status, req) => this.requestFilter(req)(status),
+        watch: [
+          query.watch(relationships, (event, _: RetrieveRequest) =>
+            this.affectedKeys(event),
+          ),
+          query.watch(labels.store, (event) => this.statusesLabeledBy(event.key)),
+        ],
+      },
+      compose: (record) => this.compose(record),
+      single: {
+        schema: z
+          .union([
+            z.strictObject({ key: keyZ, includeLabels: z.boolean().optional() }),
+            keyZ.transform((key) => ({ key })),
+          ])
+          .transform(({ key }) => key),
+        space: single,
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
   async retrieve<DetailsSchema extends z.ZodType>(
-    args: SingleRetrieveArgs & { detailsSchema?: DetailsSchema },
+    params: SingleRetrieveParams & { detailsSchema?: DetailsSchema },
   ): Promise<Status<DetailsSchema>>;
-  async retrieve(args: SingleRetrieveArgs): Promise<Status>;
-  async retrieve(args: MultiRetrieveArgs): Promise<Status[]>;
+  async retrieve(params: Key | SingleRetrieveParams): Promise<Status>;
+  async retrieve(params: MultiRetrieveParams): Promise<Status[]>;
   async retrieve<DetailsSchema extends z.ZodType = z.ZodNever>(
-    args: RetrieveArgs & { detailsSchema?: DetailsSchema },
+    rawParams: Key | (RetrieveParams & { detailsSchema?: DetailsSchema }),
   ): Promise<Status<DetailsSchema> | Status<DetailsSchema>[]> {
-    const isSingle = "key" in args;
-    const res = await this.client.send(
-      "/status/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResponseZ<DetailsSchema>(args.detailsSchema),
-    );
-    checkForMultipleOrNoResults("Status", args, res.statuses, isSingle);
-    const statuses = res.statuses as Status<DetailsSchema>[];
-    return isSingle ? statuses[0] : statuses;
+    const params = typeof rawParams === "string" ? { key: rawParams } : rawParams;
+    const { detailsSchema, ...rest } = params;
+    const isSingle = "key" in rest;
+    // Schema-parametrized retrieves validate details for one caller; their
+    // results are not shared through the cache.
+    if (detailsSchema != null) {
+      const statuses = await this.execRetrieve<DetailsSchema>(params);
+      checkForMultipleOrNoResults("Status", params, statuses, isSingle);
+      return isSingle ? statuses[0] : statuses;
+    }
+    if (isSingle) return (await super.retrieve(rest)) as Status<DetailsSchema>;
+    return (await super.retrieve(rest)) as Status<DetailsSchema>[];
   }
 
   async set<DetailsSchema extends z.ZodType>(
@@ -91,30 +180,218 @@ export class Client {
   ): Promise<Status<DetailsSchema>>;
   async set(status: New, opts?: SetOptions): Promise<Status>;
   async set(statuses: New[], opts?: SetOptions): Promise<Status[]>;
+  async set(statuses: New | New[], opts?: SetOptions): Promise<Status | Status[]>;
   async set<DetailsSchema extends z.ZodType = z.ZodNever>(
     statuses: New<DetailsSchema> | New<DetailsSchema>[],
     opts: SetOptions & { detailsSchema?: DetailsSchema } = {},
   ): Promise<Status<DetailsSchema> | Status<DetailsSchema>[]> {
     const isMany = Array.isArray(statuses);
-    const res = await this.client.send(
-      "/status/set",
-      {
-        statuses: array.toArray(statuses),
-        parent: opts.parent,
-      },
-      setReqZ(opts.detailsSchema),
-      setResZ(opts.detailsSchema),
-    );
+    // Filling the schema defaults up front gives every status a key, so the cache can
+    // hold it before the Core answers.
+    const schema = statusZ<DetailsSchema>({ details: opts.detailsSchema });
+    const normalized = array
+      .toArray(statuses)
+      .map((status) => schema.parse(status)) as Status<DetailsSchema>[];
+    const apply = () => [this.store.set(normalized)];
+    const res = await query.optimistic({
+      rollbacks: apply(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/status/set",
+          {
+            statuses: normalized as z.input<
+              ReturnType<typeof setReqZ<DetailsSchema>>
+            >["statuses"],
+            parent: opts.parent,
+          },
+          setReqZ(opts.detailsSchema),
+          setResZ(opts.detailsSchema),
+        ),
+    });
     const created = res.statuses as Status<DetailsSchema>[];
+    this.store.set(created);
     return isMany ? created : created[0];
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/status/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      emptyResZ,
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const stat = await this.retrieve(key);
+    const renamed = { ...stat, name };
+    await query.optimistic({
+      rollbacks: [
+        this.store.set(renamed),
+        this.cfg.ontology.cache.renameResource(ontologyID(key), name),
+      ],
+      onOptimistic: opts.onOptimistic,
+      commit: async () => await this.set(renamed),
+    });
+  }
+
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => [
+      this.store.delete(keysArr),
+      this.cfg.ontology.cache.relationships.delete((r) =>
+        keysArr.some((key) => label.matchLabeledBy(r, ontologyID(key))),
+      ),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/status/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
+  }
+
+  /** Subscribes to every status set delivered to the cache. */
+  onSet(handler: (status: Status) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "set") handler(event.value);
+    });
+  }
+
+  /** Subscribes to every status 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<DetailsSchema extends z.ZodType = z.ZodNever>(
+    params: RetrieveParams & { detailsSchema?: DetailsSchema },
+  ): Promise<Status<DetailsSchema>[]> {
+    const res = await this.cfg.unary.send(
+      "/status/retrieve",
+      params,
+      retrieveParamsZ,
+      retrieveResponseZ<DetailsSchema>(params.detailsSchema),
+    );
+    return res.statuses as Status<DetailsSchema>[];
+  }
+
+  /** Rebuilds a cached status with its cached labels attached. */
+  private compose(cached: Status): Status {
+    const labels = label.cachedLabelsOf(
+      this.cfg.ontology.cache.relationships,
+      this.cfg.labels.store,
+      ontologyID(cached.key),
     );
+    return { ...cached, labels };
+  }
+
+  /** Writes a fetched status and its included label relationships. */
+  private writeThrough(status: Status): void {
+    this.store.set(status);
+    if (status.labels == null) return;
+    this.cfg.labels.store.set(status.labels);
+    const id = ontologyID(status.key);
+    status.labels.forEach((l) => {
+      const rel: ontology.Relationship = {
+        from: id,
+        type: label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE,
+        to: label.ontologyID(l.key),
+      };
+      this.cfg.ontology.cache.relationships.set(
+        ontology.relationshipToString(rel),
+        rel,
+      );
+    });
+  }
+
+  /** Fetches statuses and writes their included labels through the caches. */
+  private async fetchThrough(req: RetrieveRequest): Promise<Status[]> {
+    const statuses = await this.execRetrieve({ ...BASE_REQUEST, ...req });
+    statuses.forEach((s) => this.writeThrough(s));
+    return statuses;
+  }
+
+  private async fetchSingle(key: Key): Promise<Status> {
+    const cached = this.store.get(key);
+    if (cached != null) return cached;
+    const statuses = await this.fetchThrough({ keys: [key] });
+    checkForMultipleOrNoResults("Status", key, statuses, true);
+    return statuses[0];
+  }
+
+  /**
+   * Fetches a labeled-by target the cache is missing so composition sees it.
+   * The fetched label lands in the label table, which recomposes answers.
+   */
+  private ensureLabel(rel: ontology.Relationship): void {
+    if (rel.to.type !== "label" || this.cfg.labels.store.has(rel.to.key)) return;
+    this.cfg.labels
+      .retrieve(rel.to.key)
+      .catch((exc: unknown) =>
+        this.cfg.cache.onError(
+          new Error("failed to fetch status label", { cause: exc }),
+        ),
+      );
+  }
+
+  /** Reports whether the status is labeled by the given label. */
+  private isLabeledBy(status: Key, labelKey: label.Key): boolean {
+    return this.cfg.ontology.cache.relationships.has(
+      ontology.relationshipToString({
+        from: ontologyID(status),
+        type: label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE,
+        to: label.ontologyID(labelKey),
+      }),
+    );
+  }
+
+  /** Statuses whose labels the relationship event changes; backfills the label. */
+  private affectedKeys(
+    event: query.TableEvent<string, ontology.Relationship>,
+  ): Key[] | null {
+    const rel =
+      event.variant === "set" ? event.value : ontology.relationshipZ.parse(event.key);
+    if (
+      rel.type !== label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE ||
+      rel.from.type !== "status"
+    )
+      return null;
+    if (event.variant === "set") this.ensureLabel(rel);
+    return [rel.from.key];
+  }
+
+  /** Returns the keys of cached statuses labeled by the given label. */
+  private statusesLabeledBy(labelKey: label.Key): Key[] {
+    return this.cfg.ontology.cache.relationships
+      .get(
+        (r) =>
+          r.type === label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE &&
+          r.from.type === "status" &&
+          r.to.type === "label" &&
+          r.to.key === labelKey,
+      )
+      .map((r) => r.from.key);
+  }
+
+  /**
+   * Client-side matching for a request: key sets, variants, and label
+   * membership via the relationship table. Server-computed shapes (search,
+   * limit/offset) never reach this filter; they refetch instead.
+   */
+  private requestFilter(req: RetrieveRequest): (s: Status) => boolean {
+    const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+    const variantSet = primitive.isNonZero(req.variants)
+      ? new Set(req.variants)
+      : undefined;
+    return (s) => {
+      if (keySet != null && !keySet.has(s.key)) return false;
+      if (variantSet != null && !variantSet.has(s.variant)) return false;
+      if (
+        primitive.isNonZero(req.hasLabels) &&
+        !req.hasLabels.some((key) => this.isLabeledBy(s.key, key))
+      )
+        return false;
+      return true;
+    };
   }
 }

package/src/status/external.ts

@@ -9,3 +9,5 @@
 
 export * from "@/status/client";
 export * from "@/status/payload";
+export * from "@/status/status";
+export * from "@/status/types.gen";

package/src/status/payload.ts

@@ -7,30 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { status } from "@synnaxlabs/x";
-import { z } from "zod";
-
 import { ontology } from "@/ontology";
-
-export const keyZ = z.string();
-export type Key = z.infer<typeof keyZ>;
-
-// Wrapper functions with single-param style
-export const statusZ = <Details extends z.ZodType = z.ZodNever>(
-  detailsSchema?: Details,
-) => status.statusZ({ details: detailsSchema });
-
-export const newZ = <DetailsSchema extends z.ZodType = z.ZodNever>(
-  detailsSchema?: DetailsSchema,
-) => status.newZ({ details: detailsSchema }).omit({ labels: true });
-
-// Input type derived from Zod schema for consistency
-export type New<DetailsSchema extends z.ZodType = z.ZodNever> = z.input<
-  ReturnType<typeof newZ<DetailsSchema>>
->;
-
-// Output type re-exported from x package
-export type Status<Details extends z.ZodType = z.ZodNever> = status.Status<Details>;
+import { type Key } from "@/status/types.gen";
 
 export const SET_CHANNEL_NAME = "sy_status_set";
 export const DELETE_CHANNEL_NAME = "sy_status_delete";