@procedures/client 0.49.1 → 0.51.0

package/src/events/index.ts

@@ -63,7 +63,9 @@ export type { EventPublisherOptions, TopicRule, TopicCall } from "./publisher.js
 export type { RightsChange, RightsScope, RightsScopes, SubscriptionRecheck } from "./recheck.js";
 // The live state: keyed values in memory on a topic, with a snapshot and a time limit (LIVE-STATE-2026-11.md)
 export {
+  DEFAULT_LIVE_BYTES,
   DEFAULT_LIVE_KEYS,
+  DEFAULT_LIVE_TOPIC_BYTES,
   DEFAULT_LIVE_TOPICS,
   DEFAULT_LIVE_VALUE_BYTES,
   LIVE_SET_PATH,

package/src/events/live-state.ts

@@ -40,6 +40,16 @@ export const DEFAULT_LIVE_KEYS = 1024;
 export const DEFAULT_LIVE_VALUE_BYTES = 16384;
 /** The default limit of the topics of one live state. */
 export const DEFAULT_LIVE_TOPICS = 4096;
+/**
+ * The default limit of the bytes of the values of one topic, as JSON. This limit bounds a snapshot and a window event.
+ * In the bench `live-limits` (run 42152574477), a full topic at this limit kept 1,075,659 bytes of heap.
+ */
+export const DEFAULT_LIVE_TOPIC_BYTES = 1_048_576;
+/**
+ * The default limit of the bytes of all values of one live state, as JSON. In the bench `live-limits` (run 42152574477),
+ * a full state kept 68,842,177 bytes: 1.53 percent of a heap limit of 4,496,293,888 bytes.
+ */
+export const DEFAULT_LIVE_BYTES = 67_108_864;
 
 /** The prefix of each live topic. */
 const PREFIX = "live.";
@@ -169,6 +179,18 @@ export interface LiveStateOptions {
    * @default DEFAULT_LIVE_TOPICS
    */
   maxTopics?: number | undefined;
+  /**
+   * The limit of the bytes of the values of one topic, as JSON. A set that takes a topic above the limit gets
+   * `FORBIDDEN`. A set that makes a value smaller always goes. This limit bounds a snapshot and a window event.
+   * @default DEFAULT_LIVE_TOPIC_BYTES
+   */
+  maxTopicBytes?: number | undefined;
+  /**
+   * The limit of the bytes of all values of this live state, as JSON. A set that takes the state above the limit gets
+   * `FORBIDDEN`. This limit bounds the memory of the state, because the product of the other limits does not.
+   * @default DEFAULT_LIVE_BYTES
+   */
+  maxBytes?: number | undefined;
   /**
    * The clock of the deadlines and of the window. A test gives the `fakeClock` of
    * `@mark1russell7/service/testing`.
@@ -233,6 +255,8 @@ interface Slot {
   readonly state: TopicState;
   readonly key: string;
   entry: LiveEntry;
+  /** The bytes of the value, as JSON. */
+  bytes: number;
   deadline: number;
   owner: string | undefined;
 }
@@ -249,6 +273,8 @@ interface TopicState {
   readonly keys: Map<string, Slot>;
   readonly stop: Unsubscribe;
   readonly windowMs: number;
+  /** The bytes of the values of the keys, as JSON. */
+  bytes: number;
   waiting: Waiting | undefined;
   /** This field holds the timer of the open window. It is undefined when the topic is idle. */
   window: Cancel | undefined;
@@ -261,6 +287,17 @@ function isLiveEvent(value: unknown): value is LiveEvent {
   return typeof event.origin === "string" && Array.isArray(event.set) && Array.isArray(event.gone);
 }
 
+/** True when a text has a character outside ASCII. */
+const NOT_ASCII = /[^\u0000-\u007f]/;
+let encoder: InstanceType<typeof TextEncoder> | undefined;
+
+/** This function gives the UTF-8 bytes of a text. An ASCII text has one byte for each character, and needs no encode. */
+function utf8Bytes(text: string): number {
+  if (!NOT_ASCII.test(text)) return text.length;
+  encoder ??= new TextEncoder();
+  return encoder.encode(text).length;
+}
+
 /** This function gives a refusal of a set. */
 function refused(message: string, reason: "write-not-allowed" | "partition-not-allowed", path: readonly string[] = LIVE_SET_PATH): InvocationError {
   return new InvocationError("FORBIDDEN", message, [...path], reason);
@@ -298,6 +335,10 @@ export class LiveState {
   private readonly maxKeys: number;
   private readonly maxValueBytes: number;
   private readonly maxTopics: number;
+  private readonly maxTopicBytes: number;
+  private readonly maxBytes: number;
+  /** The bytes of all values, as JSON. */
+  private totalBytes = 0;
   private readonly origin = newOrigin();
   private readonly topics = new Map<string, TopicState>();
   /** Each key in the order of its last set. All keys have the same time, so this is the order of the deadlines. */
@@ -321,6 +362,8 @@ export class LiveState {
     this.maxKeys = options.maxKeysPerTopic ?? DEFAULT_LIVE_KEYS;
     this.maxValueBytes = options.maxValueBytes ?? DEFAULT_LIVE_VALUE_BYTES;
     this.maxTopics = options.maxTopics ?? DEFAULT_LIVE_TOPICS;
+    this.maxTopicBytes = options.maxTopicBytes ?? DEFAULT_LIVE_TOPIC_BYTES;
+    this.maxBytes = options.maxBytes ?? DEFAULT_LIVE_BYTES;
     this.procedures = [this.setProcedure(host.topicSchema), this.snapshotProcedure(host.topicSchema), this.leaveProcedure(host.topicSchema)];
   }
 
@@ -329,6 +372,11 @@ export class LiveState {
     return this.deadlines.size;
   }
 
+  /** The bytes of the values of this state, as JSON. */
+  get bytes(): number {
+    return this.totalBytes;
+  }
+
   /**
    * The topic of the bus for a live topic of a call, or undefined for another topic. The publisher
    * calls it for each subscription and each re-check, so a change of the partition ends a
@@ -355,19 +403,23 @@ export class LiveState {
    */
   set(topic: string, key: string, value: unknown, options: LiveSetOptions = {}): number {
     if (this.closed) throw refused("The live state is closed", "write-not-allowed");
-    this.checkValue(value);
+    const bytes = this.checkValue(value);
     const state = this.stateOf(topic);
     if (!state) throw refused(`The live state has its limit of ${this.maxTopics} topics`, "write-not-allowed");
+    let slot = state.keys.get(key);
+    if (!slot && state.keys.size >= this.maxKeys) throw refused(`The live topic "${topic}" has its limit of ${this.maxKeys} keys`, "write-not-allowed");
+    const more = bytes - (slot?.bytes ?? 0);
+    if (more > 0 && state.bytes + more > this.maxTopicBytes) throw refused(`The live topic "${topic}" has its limit of ${this.maxTopicBytes} bytes`, "write-not-allowed");
+    if (more > 0 && this.totalBytes + more > this.maxBytes) throw refused(`The live state has its limit of ${this.maxBytes} bytes`, "write-not-allowed");
     const at = this.clock.now();
     const entry: LiveEntry = options.by === undefined ? { key, value, at } : { key, value, by: options.by, at };
-    let slot = state.keys.get(key);
     if (slot) {
       slot.entry = entry;
     } else {
-      if (state.keys.size >= this.maxKeys) throw refused(`The live topic "${topic}" has its limit of ${this.maxKeys} keys`, "write-not-allowed");
-      slot = { state, key, entry, deadline: 0, owner: undefined };
+      slot = { state, key, entry, bytes: 0, deadline: 0, owner: undefined };
       state.keys.set(key, slot);
     }
+    this.resize(slot, bytes);
     this.renew(slot, at);
     this.own(slot, options.owner);
     this.queue(state, (waiting) => {
@@ -421,15 +473,26 @@ export class LiveState {
     this.topics.clear();
     this.deadlines.clear();
     this.owned.clear();
+    this.totalBytes = 0;
   }
 
-  /** This method refuses a value above the limit. A text has at most 3 bytes for each UTF-16 unit. */
-  private checkValue(value: unknown): void {
+  /**
+   * This method refuses a value above the limit, and gives the bytes of a value that fits. A text has at least one
+   * byte for each UTF-16 unit, so a longer text needs no encode.
+   */
+  private checkValue(value: unknown): number {
     const text = JSON.stringify(value);
     if (text === undefined) throw refused("A live value must have a JSON form", "write-not-allowed");
-    const fits = text.length * 3 <= this.maxValueBytes
-      || (text.length <= this.maxValueBytes && new TextEncoder().encode(text).length <= this.maxValueBytes);
-    if (!fits) throw refused(`A live value has more than ${this.maxValueBytes} bytes`, "write-not-allowed");
+    const bytes = text.length > this.maxValueBytes ? Infinity : utf8Bytes(text);
+    if (bytes > this.maxValueBytes) throw refused(`A live value has more than ${this.maxValueBytes} bytes`, "write-not-allowed");
+    return bytes;
+  }
+
+  /** This method gives a key the bytes of its new value, and changes the sums of its topic and of the state. */
+  private resize(slot: Slot, bytes: number): void {
+    slot.state.bytes += bytes - slot.bytes;
+    this.totalBytes += bytes - slot.bytes;
+    slot.bytes = bytes;
   }
 
   /**
@@ -449,7 +512,7 @@ export class LiveState {
       if (this.topics.size >= this.maxTopics) return undefined;
     }
     const stop = this.bus.on<unknown>(topic, (event) => this.heard(topic, event));
-    const state: TopicState = { topic, keys: new Map(), stop, windowMs: toMs(this.windowOf(topic), "window"), waiting: undefined, window: undefined };
+    const state: TopicState = { topic, keys: new Map(), stop, windowMs: toMs(this.windowOf(topic), "window"), bytes: 0, waiting: undefined, window: undefined };
     this.topics.set(topic, state);
     return state;
   }
@@ -462,13 +525,21 @@ export class LiveState {
     const now = this.clock.now();
     for (const entry of event.set) {
       let slot = state.keys.get(entry.key);
+      const bytes = this.bytesOf(entry.value);
+      const more = bytes - (slot?.bytes ?? 0);
+      if (bytes > this.maxValueBytes || (more > 0 && (state.bytes + more > this.maxTopicBytes || this.totalBytes + more > this.maxBytes))) {
+        // A value that does not fit here leaves no old value of the key: the subscribers got the new one from the bus
+        if (slot) this.end(slot, "expired", false);
+        continue;
+      }
       if (slot) {
         slot.entry = entry;
       } else {
         if (state.keys.size >= this.maxKeys) continue;
-        slot = { state, key: entry.key, entry, deadline: 0, owner: undefined };
+        slot = { state, key: entry.key, entry, bytes: 0, deadline: 0, owner: undefined };
         state.keys.set(entry.key, slot);
       }
+      this.resize(slot, bytes);
       // The connection of this key is on the other host: its deadline ends the key if that host dies
       this.own(slot, undefined);
       this.renew(slot, now);
@@ -479,6 +550,12 @@ export class LiveState {
     }
   }
 
+  /** The bytes of a value of another host, as JSON. A value with no JSON form has no place. */
+  private bytesOf(value: unknown): number {
+    const text = JSON.stringify(value);
+    return text === undefined ? Infinity : utf8Bytes(text);
+  }
+
   /** This method moves a key to the end of the deadlines. */
   private renew(slot: Slot, now: number): void {
     slot.deadline = now + this.expiresMs;
@@ -507,6 +584,7 @@ export class LiveState {
     this.own(slot, undefined);
     this.deadlines.delete(slot);
     slot.state.keys.delete(slot.key);
+    this.resize(slot, 0);
     if (!publish) return;
     this.queue(slot.state, (waiting) => {
       waiting.set.delete(slot.key);

package/src/events/publisher.ts

@@ -48,6 +48,7 @@ import { admittedValue, rowsOf } from "./rows.js";
 import { realClock, type Clock } from "../clock.js";
 import { SubscriptionRechecks, type RecheckCause, type RightsChange, type RightsScope, type RightsScopes, type SubscriptionRecheck } from "./recheck.js";
 import { DROPPED, RowHintFilter, collectionInvocation, collectionRulesOf, markFilteredTopic, type HintFilterMode } from "../procedures/collection/hint-filter.js";
+import { shareEncoding } from "../frame-encoding.js";
 
 /** The number of topics that one subscription can name. */
 export const MAX_SUBSCRIPTION_TOPICS = 64;
@@ -327,7 +328,8 @@ class TopicSubscription implements AsyncIterableIterator<EventItem> {
    */
   private deliver(event: QueuedEvent): Promise<IteratorResult<EventItem>> {
     const filtered = this.filters?.get(event.topic)?.apply(event.data);
-    if (!filtered) return this.item(event.topic, event.data);
+    // Each subscriber of the topic gets this same data, so a transport encodes it once (roadmap CLI-112)
+    if (!filtered) return this.item(event.topic, shareEncoding(event.data, this));
     return filtered.then(
       (data) => (data === DROPPED ? this.next() : this.item(event.topic, data)),
       // A filter that fails: the subscriber reads the changes itself

package/src/frame-encoding.ts

@@ -0,0 +1,101 @@
+/**
+ * The encoding of a frame with a shared value (roadmap CLI-112). The publisher of events sends the same event to each
+ * subscriber. Each connection puts it in its own frame, with its own id and number. Without this module, each
+ * connection encodes the whole event again, so one event costs subscribers x event bytes.
+ *
+ * The publisher marks the data of an event as shared, once for each receiver of the event. `encodeFrame` encodes a
+ * marked value once, at its first frame, and puts that text in each later frame of the same event. The text of a frame
+ * is byte-equal to `JSON.stringify` of the frame at that first encode.
+ *
+ * A source can publish the same object again after a change. A receiver that gets the object a second time starts a
+ * new event, so the next frame encodes the object again. The text of one event is the value at its first encode.
+ */
+
+/** One event of a shared value: the receivers that got it, and its text after the first frame. */
+interface Share {
+  readonly receivers: WeakSet<object>;
+  text?: string;
+}
+
+/** The current event of each shared value. */
+const shares = new WeakMap<object, Share>();
+/** The count of the encodes of shared values, for the tests. */
+let encodes = 0;
+
+/**
+ * The depth of the frame that `encodeFrame` examines for a shared value. A WebSocket frame and an NDJSON line hold an
+ * event at depth 2: the frame, its `payload`, then the `data` of the payload.
+ */
+const DEPTH = 3;
+
+/**
+ * This function marks a value as shared by the frames of the receivers of one event, and gives the value back. When the
+ * receiver got the value before, the value starts a new event, and its first frame encodes the value again.
+ */
+export function shareEncoding<T>(value: T, receiver: object): T {
+  if (typeof value !== "object" || value === null) return value;
+  const share = shares.get(value);
+  if (share === undefined || share.receivers.has(receiver)) shares.set(value, { receivers: new WeakSet([receiver]) });
+  else share.receivers.add(receiver);
+  return value;
+}
+
+/** This function gives the count of the encodes of shared values since the start of the process. */
+export function sharedEncodes(): number {
+  return encodes;
+}
+
+/**
+ * This function gives the JSON text of a frame. The function encodes a shared plain object once for all frames. The
+ * object can be the frame, or a value in a plain object of the frame up to depth 3. The text is byte-equal to
+ * `JSON.stringify(frame)`.
+ */
+export function encodeFrame(frame: unknown): string {
+  const text = encode(frame, DEPTH);
+  // `JSON.stringify` gives undefined for a value with no JSON form. A frame is always an object
+  if (text === undefined) throw new TypeError("A frame must have a JSON form");
+  return text;
+}
+
+/** The text of a shared value, from the first encode of its current event. */
+function sharedText(value: object, share: Share): string | undefined {
+  if (share.text !== undefined) return share.text;
+  encodes++;
+  const text = JSON.stringify(value);
+  if (text !== undefined) share.text = text;
+  return text;
+}
+
+/** True for an object that `JSON.stringify` writes key by key: a plain object with no `toJSON`. */
+function isPlain(value: object): value is Record<string, unknown> {
+  if (Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  return typeof (value as { toJSON?: unknown }).toJSON !== "function";
+}
+
+/**
+ * The JSON text of the value of a key, as `JSON.stringify` writes it in an object. A `toJSON` method gets the key, as
+ * in the object.
+ */
+function asProperty(key: string, value: unknown): string | undefined {
+  const text = JSON.stringify({ [key]: value });
+  return text === "{}" ? undefined : text.slice(JSON.stringify(key).length + 2, -1);
+}
+
+/** The JSON text of the value of a key, or undefined when the value has no JSON form, as `JSON.stringify` gives. */
+function encode(value: unknown, depth: number, key = ""): string | undefined {
+  // Only an object and a bigint can have a `toJSON` method
+  if (typeof value === "bigint") return asProperty(key, value);
+  if (typeof value !== "object" || value === null) return JSON.stringify(value);
+  if (!isPlain(value)) return asProperty(key, value);
+  const share = shares.get(value);
+  if (share !== undefined) return sharedText(value, share);
+  if (depth === 0) return JSON.stringify(value);
+  const parts: string[] = [];
+  for (const name of Object.keys(value)) {
+    const part = encode(value[name], depth - 1, name);
+    if (part !== undefined) parts.push(`${JSON.stringify(name)}:${part}`);
+  }
+  return `{${parts.join(",")}}`;
+}

package/src/procedures/collection/storage.ts

@@ -186,8 +186,8 @@ export type StorageObserver<T> = (changes: StorageChangeBatch<T>) => void;
  * - The order of a full result is the order of the entries. The order of a delta is the order of
  *   the last change of each id.
  * - A result gives each write at least one time. A write can come again in two cases, with the same
- *   value or a later value. A full result takes its version before it lists the items, so it can
- *   hold a write above that version, and the next delta gives the write again. A write that ends
+ *   value or a later value. A full result takes its version after it lists the items, and it can
+ *   hold a write above that version, so the next delta gives the write again. A write that ends
  *   after its lease can come again in a later delta, with a new version. A consumer applies a change
  *   by its id, and does not count changes.
  */