@synnaxlabs/client 0.57.0 → 0.57.2

package/src/query/indexes.ts

@@ -0,0 +1,81 @@
+// Copyright 2026 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 record, type state } from "@synnaxlabs/x";
+
+/**
+ * An exact-match secondary index over a table's live entries. `extract` reads one
+ * index value from each entry. Register the index on its owning table's `indexes`
+ * param; the table keeps it current across every mutation, rollbacks and resets
+ * included. Tombstones are never indexed.
+ */
+export class LookupIndex<
+  Key extends record.Key = record.Key,
+  Value extends state.State = state.State,
+  IndexValue extends record.Key = record.Key,
+> {
+  private readonly extract: (value: Value) => IndexValue;
+  private readonly buckets = new Map<IndexValue, Map<Key, Value>>();
+  private readonly indexed = new Map<Key, IndexValue>();
+
+  constructor(extract: (value: Value) => IndexValue) {
+    this.extract = extract;
+  }
+
+  /** Returns the entries whose extracted index value equals the given value. */
+  get(value: IndexValue): Value[] {
+    const bucket = this.buckets.get(value);
+    if (bucket == null) return [];
+    return Array.from(bucket.values());
+  }
+
+  /**
+   * Records the entry, relocating it when its extracted value changed.
+   * Cache-internal surface: called by the owning table, not domain code.
+   */
+  set(key: Key, value: Value): void {
+    const next = this.extract(value);
+    const prev = this.indexed.get(key);
+    if (prev !== undefined && prev !== next) this.unbucket(prev, key);
+    let bucket = this.buckets.get(next);
+    if (bucket == null) {
+      bucket = new Map();
+      this.buckets.set(next, bucket);
+    }
+    bucket.set(key, value);
+    this.indexed.set(key, next);
+  }
+
+  /**
+   * Removes any mapping for the given entry key.
+   * Cache-internal surface: called by the owning table, not domain code.
+   */
+  delete(key: Key): void {
+    const prev = this.indexed.get(key);
+    if (prev === undefined) return;
+    this.unbucket(prev, key);
+    this.indexed.delete(key);
+  }
+
+  /**
+   * Discards every mapping.
+   * Cache-internal surface: called by the owning table, not domain code.
+   */
+  reset(): void {
+    this.buckets.clear();
+    this.indexed.clear();
+  }
+
+  private unbucket(value: IndexValue, key: Key): void {
+    const bucket = this.buckets.get(value);
+    if (bucket == null) return;
+    bucket.delete(key);
+    if (bucket.size === 0) this.buckets.delete(value);
+  }
+}

package/src/query/table.ts

@@ -23,6 +23,7 @@ import type z from "zod";
 
 import { NotFoundError } from "@/errors";
 import { Deleted } from "@/query/deleted";
+import { type LookupIndex } from "@/query/indexes";
 import { type Listener } from "@/query/streamer";
 
 /**
@@ -98,6 +99,11 @@ export interface TableParams<
    * @default TimeSpan.milliseconds(10)
    */
   fetchDebounce?: CrudeTimeSpan;
+  /**
+   * Secondary indexes over the table's live entries. The table keeps each current
+   * across every mutation, rollbacks and resets included.
+   */
+  indexes?: Array<LookupIndex<Key, Value>>;
 }
 
 /**
@@ -156,6 +162,7 @@ export class Table<
     Key[],
     Array<Keyed<Key, Value>>
   > | null;
+  private readonly indexes: Array<LookupIndex<Key, Value>>;
   private gen = 0;
 
   constructor({
@@ -164,11 +171,13 @@ export class Table<
     fetch,
     hydrate = "set",
     fetchDebounce = DEFAULT_FETCH_DEBOUNCE,
+    indexes = [],
   }: TableParams<Key, Value>) {
     this.onError = onError;
     this.equal = equal;
     this.fetchEntries = fetch;
     this.hydrateMode = hydrate;
+    this.indexes = indexes;
     this.fetchBatcher =
       fetch == null
         ? null
@@ -188,6 +197,16 @@ export class Table<
           });
   }
 
+  private applySet(key: Key, value: Value): void {
+    this.entries.set(key, value);
+    for (const index of this.indexes) index.set(key, value);
+  }
+
+  private applyDelete(key: Key): void {
+    this.entries.delete(key);
+    for (const index of this.indexes) index.delete(key);
+  }
+
   private setOne(
     key: Key,
     value: state.SetArg<Value | undefined>,
@@ -197,16 +216,16 @@ export class Table<
     if (next == null || (prev != null && this.equal(next, prev, key))) return undefined;
     const prevTombstone = this.tombstones.get(key);
     this.tombstones.delete(key);
-    this.entries.set(key, next);
+    this.applySet(key, next);
     this.notify({ variant: "set", key, value: next });
 
     return () => {
       if (prev === undefined) {
-        this.entries.delete(key);
+        this.applyDelete(key);
         if (prevTombstone != null) this.tombstones.set(key, prevTombstone);
         this.notify({ variant: "delete", key });
       } else {
-        this.entries.set(key, prev);
+        this.applySet(key, prev);
         this.notify({ variant: "set", key, value: prev });
       }
     };
@@ -375,7 +394,7 @@ export class Table<
 
     this.batch(() =>
       toDelete.forEach(({ key: k, value }) => {
-        this.entries.delete(k);
+        this.applyDelete(k);
         if (tombstone && value != null)
           this.tombstones.set(k, new Deleted(value, TimeStamp.now()));
         this.notify({ variant: "delete", key: k });
@@ -387,7 +406,7 @@ export class Table<
         toDelete.forEach(({ key: k, value }) => {
           if (value == null) return;
           this.tombstones.delete(k);
-          this.entries.set(k, value);
+          this.applySet(k, value);
           this.notify({ variant: "set", key: k, value });
         }),
       );
@@ -426,6 +445,7 @@ export class Table<
     this.gen++;
     this.entries.clear();
     this.tombstones.clear();
+    for (const index of this.indexes) index.reset();
   }
 
   /**

package/src/ranger/client.ts

@@ -340,16 +340,13 @@ const watchRelationships = <Q extends query.Params>(
     affectedRangeKeys(relOfEvent(event)),
   );
 
-const rangesWithLabel = (
-  relationships: query.Table<string, ontology.Relationship>,
-  key: label.Key,
-): Key[] | null => {
-  const keys = relationships
-    .get(
+const rangesWithLabel = (cache: ontology.Cache, key: label.Key): Key[] | null => {
+  const keys = cache
+    .relationshipsTo(label.ontologyID(key))
+    .filter(
       (r) =>
         r.type === label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE &&
-        r.from.type === "range" &&
-        r.to.key === key,
+        r.from.type === "range",
     )
     .map((r) => r.from.key);
   return keys.length === 0 ? null : keys;
@@ -358,10 +355,10 @@ const rangesWithLabel = (
 /** Projects label content changes onto the ranges they label. */
 const watchLabels = <Q extends query.Params>(
   labels: query.Table<label.Key, label.Label>,
-  relationships: query.Table<string, ontology.Relationship>,
+  cache: ontology.Cache,
 ): query.Watch<Q, Key> =>
   query.watch<Q, Key, label.Key, label.Label>(labels, (event) =>
-    rangesWithLabel(relationships, event.key),
+    rangesWithLabel(cache, event.key),
   );
 
 /** Config for {@link Client}. */
@@ -422,7 +419,9 @@ export class Client extends query.Retriever<
         query.deriveWatch(relationships, (event) =>
           affectedRangeKeys(relOfEvent(event)),
         ),
-        query.deriveWatch(labels, (event) => rangesWithLabel(relationships, event.key)),
+        query.deriveWatch(labels, (event) =>
+          rangesWithLabel(ontologyClient.cache, event.key),
+        ),
       ],
     });
     const single = cache.queries<Key | Name, Range, Key, Range>({
@@ -443,7 +442,7 @@ export class Client extends query.Retriever<
         matches: (r, query) => this.requestMatches(r, query),
         watch: [
           watchRelationships<RetrieveRequest>(relationships),
-          watchLabels<RetrieveRequest>(labels, relationships),
+          watchLabels<RetrieveRequest>(labels, ontologyClient.cache),
         ],
       },
       compose: (r) => this.composeOne(r),
@@ -597,7 +596,7 @@ export class Client extends query.Retriever<
   private composeOne(cached: Range): Range {
     const id = ontologyID(cached.key);
     const labels = label.cachedLabelsOf(
-      this.cfg.ontology.cache.relationships,
+      this.cfg.ontology.cache,
       this.cfg.labels.store,
       id,
     );
@@ -642,6 +641,17 @@ export class Client extends query.Retriever<
     }
   }
 
+  /** Writes a fetch response as one batch per table, so each table flushes once. */
+  private writeThroughMany(ranges: Range[]): void {
+    this.store.batch(() =>
+      this.cfg.labels.store.batch(() =>
+        this.cfg.ontology.cache.relationships.batch(() =>
+          ranges.forEach((r) => this.writeThrough(r)),
+        ),
+      ),
+    );
+  }
+
   /**
    * Fetches the given keys with labels and parents included, writing them and
    * their relationships through. Powers the table's fetch primitive.
@@ -652,7 +662,7 @@ export class Client extends query.Retriever<
       keys,
       ignoreNotFoundError: true,
     });
-    ranges.forEach((r) => this.writeThrough(r));
+    this.writeThroughMany(ranges);
     return ranges;
   }
 
@@ -686,7 +696,7 @@ export class Client extends query.Retriever<
   private async fetchRequest(query: RetrieveRequest): Promise<Range[]> {
     if (isKeysOnly(query)) return await this.store.retrieve(query.keys);
     const ranges = await this.execRetrieve({ ...BASE_REQUEST, ...query });
-    ranges.forEach((r) => this.writeThrough(r));
+    this.writeThroughMany(ranges);
     return ranges;
   }
 
@@ -701,7 +711,7 @@ export class Client extends query.Retriever<
       return false;
     if (primitive.isNonZero(req.hasLabels)) {
       const labels = label.cachedLabelsOf(
-        this.cfg.ontology.cache.relationships,
+        this.cfg.ontology.cache,
         this.cfg.labels.store,
         ontologyID(r.key),
       );

package/src/status/client.ts

@@ -99,7 +99,7 @@ export class Client extends query.Retriever<
           value: (changed, prev) => {
             const next = { ...prev, ...changed };
             const id = ontologyID(changed.key);
-            next.labels = label.cachedLabelsOf(relationships, labels.store, id);
+            next.labels = label.cachedLabelsOf(ontologyClient.cache, labels.store, id);
             return next;
           },
         }),
@@ -278,7 +278,7 @@ export class Client extends query.Retriever<
   /** 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.ontology.cache,
       this.cfg.labels.store,
       ontologyID(cached.key),
     );
@@ -307,7 +307,14 @@ export class Client extends query.Retriever<
   /** 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));
+    // One batch per table, so each table flushes once for the whole response.
+    this.store.batch(() =>
+      this.cfg.labels.store.batch(() =>
+        this.cfg.ontology.cache.relationships.batch(() =>
+          statuses.forEach((s) => this.writeThrough(s)),
+        ),
+      ),
+    );
     return statuses;
   }
 
@@ -362,13 +369,12 @@ export class Client extends query.Retriever<
 
   /** Returns the keys of cached statuses labeled by the given label. */
   private statusesLabeledBy(labelKey: label.Key): Key[] {
-    return this.cfg.ontology.cache.relationships
-      .get(
+    return this.cfg.ontology.cache
+      .relationshipsTo(label.ontologyID(labelKey))
+      .filter(
         (r) =>
           r.type === label.LABELED_BY_ONTOLOGY_RELATIONSHIP_TYPE &&
-          r.from.type === "status" &&
-          r.to.type === "label" &&
-          r.to.key === labelKey,
+          r.from.type === "status",
       )
       .map((r) => r.from.key);
   }