@rocicorp/zero 1.11.0-canary.2 → 1.11.0-canary.21

package/out/zero-cache/src/types/processes.d.ts

@@ -12,12 +12,43 @@ import EventEmitter from 'node:events';
 export declare const MESSAGE_TYPES: {
     readonly handoff: 'handoff';
     readonly status: 'status';
+    readonly clientGroupStatus: 'clientGroupStatus';
     readonly subscribe: 'subscribe';
     readonly notify: 'notify';
     readonly ready: 'ready';
     readonly backupWatermarkUpdate: 'backupWatermakUpdate';
+    readonly profile: 'profile';
+    readonly profileResponse: 'profileResponse';
 };
+export type ClientGroupStatus = {
+    readonly clientGroupID: string;
+    readonly active: boolean;
+    readonly generation?: number | undefined;
+};
+export type ClientGroupStatusMessage = ['clientGroupStatus', ClientGroupStatus];
+export type ProfileRequest = {
+    readonly id: string;
+    readonly durationMs: number;
+    readonly worker?: string | undefined;
+    readonly workerIndex?: number | undefined;
+};
+export type ProfileResponse = {
+    readonly id: string;
+    readonly name: string;
+    readonly profile?: unknown | undefined;
+    readonly error?: string | undefined;
+};
+export type ProfileMessage = ['profile', ProfileRequest];
+export type ProfileResponseMessage = ['profileResponse', ProfileResponse];
 export type Message<Payload> = [keyof typeof MESSAGE_TYPES, Payload];
+/**
+ * Subscribes the `handler` to messages of the given `type` and returns a
+ * function that unsubscribes it. Use this (rather than
+ * {@link Receiver.onMessageType()}) for handlers scoped to a request or
+ * operation rather than to the lifetime of the {@link Worker}; the
+ * `'message'` listener is otherwise retained by the Worker forever.
+ */
+export declare function subscribeToMessageType<M extends Message<unknown>>(e: EventEmitter, type: M[0], handler: (msg: M[1], sendHandle?: SendHandle) => void): () => void;
 export interface Sender {
     send<M extends Message<unknown>>(message: M, sendHandle?: SendHandle, callback?: (error: Error | null) => void): boolean;
     kill(signal?: NodeJS.Signals): void;
@@ -86,4 +117,12 @@ export declare function forkChildWorker(moduleUrl: URL, env?: NodeJS.ProcessEnv,
  * in a single process.
  */
 export declare function inProcChannel(): [Worker, Worker];
+/**
+ * Creates a {@link Worker} facade that broadcasts `send()` to all provided
+ * workers and aggregates their `'message'` events into one stream.
+ *
+ * This is useful for code that expects a single Worker for IPC (e.g.
+ * `handleProfzRequest`) but needs to reach multiple child workers.
+ */
+export declare function broadcastWorker(workers: Worker[]): Worker;
 //# sourceMappingURL=processes.d.ts.map

package/out/zero-cache/src/types/processes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/processes.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EAEhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,YAAY,MAAM,aAAa,CAAC;AAIvC;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;aACxB,OAAO,EAAE,SAAS;aAClB,MAAM,EAAE,QAAQ;aAChB,SAAS,EAAE,WAAW;aACtB,MAAM,EAAE,QAAQ;aAChB,KAAK,EAAE,OAAO;aACd,qBAAqB,EAAE,sBAAsB;CACrC,CAAC;AAEX,MAAM,MAAM,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,OAAO,aAAa,EAAE,OAAO,CAAC,CAAC;AAwCrE,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EAC7B,OAAO,EAAE,CAAC,EACV,UAAU,CAAC,EAAE,UAAU,EACvB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GACvC,OAAO,CAAC;IAEX,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,UAAW,SAAQ,MAAM,EAAE,YAAY;IACtD,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C;;;;OAIG;IACH,aAAa,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EACtC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EACV,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,GACpD,IAAI,CAAC;IAER;;;;OAIG;IACH,eAAe,CAAC,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,EACxC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EACV,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,EAAE,UAAU,KAAK,IAAI,GACpD,IAAI,CAAC;CACT;AAED,MAAM,WAAW,MAAO,SAAQ,UAAU,EAAE,QAAQ;CAAG;AAkCvD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,GAAG,IAE5B,CAAC;AAIT,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,OAAc,GAAG,IAAI,CAElE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,mBAAmB,EAAE,OAAO,GAC3B,OAAO,CAET;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,GAAG,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EACvB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAoBR;AAED,wBAAgB,eAAe,CAC7B,SAAS,EAAE,GAAG,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EACvB,GAAG,IAAI,EAAE,MAAM,EAAE,GAChB,MAAM,CAER;AAuBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CA+BhD"}
+{"version":3,"file":"processes.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/processes.ts"],"names":[],"mappings":"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"}

package/out/zero-cache/src/types/processes.js

@@ -7,11 +7,26 @@ function getMessage(type, data) {
 	if (Array.isArray(data) && data.length === 2 && data[0] === type) return data[1];
 	return null;
 }
-function onMessageType(e, type, handler) {
-	return e.on("message", (data, sendHandle) => {
+/**
+* Subscribes the `handler` to messages of the given `type` and returns a
+* function that unsubscribes it. Use this (rather than
+* {@link Receiver.onMessageType()}) for handlers scoped to a request or
+* operation rather than to the lifetime of the {@link Worker}; the
+* `'message'` listener is otherwise retained by the Worker forever.
+*/
+function subscribeToMessageType(e, type, handler) {
+	const listener = (data, sendHandle) => {
 		const msg = getMessage(type, data);
 		if (msg) handler(msg, sendHandle);
-	});
+	};
+	e.on("message", listener);
+	return () => {
+		e.off("message", listener);
+	};
+}
+function onMessageType(e, type, handler) {
+	subscribeToMessageType(e, type, handler);
+	return e;
 }
 function onceMessageType(e, type, handler) {
 	const listener = (data, sendHandle) => {
@@ -112,7 +127,31 @@ function inProcChannel() {
 		pid
 	}))];
 }
+/**
+* Creates a {@link Worker} facade that broadcasts `send()` to all provided
+* workers and aggregates their `'message'` events into one stream.
+*
+* This is useful for code that expects a single Worker for IPC (e.g.
+* `handleProfzRequest`) but needs to reach multiple child workers.
+*/
+function broadcastWorker(workers) {
+	const emitter = new EventEmitter();
+	for (const w of workers) w.on("message", (message, sendHandle) => emitter.emit("message", message, sendHandle));
+	const send = (message, sendHandle, callback) => {
+		for (const w of workers) w.send(message, sendHandle);
+		if (callback) callback(null);
+		return true;
+	};
+	const kill = (signal = "SIGTERM") => {
+		for (const w of workers) w.kill(signal);
+	};
+	return wrap(Object.assign(emitter, {
+		send,
+		kill,
+		pid
+	}));
+}
 //#endregion
-export { childWorker, parentWorker, singleProcessMode };
+export { broadcastWorker, childWorker, parentWorker, singleProcessMode, subscribeToMessageType };
 
 //# sourceMappingURL=processes.js.map

package/out/zero-cache/src/types/processes.js.map

@@ -1 +1 @@
-{"version":3,"file":"processes.js","names":[],"sources":["../../../../../zero-cache/src/types/processes.ts"],"sourcesContent":["import {\n  type ChildProcess,\n  fork,\n  type SendHandle,\n  type Serializable,\n} from 'node:child_process';\nimport EventEmitter from 'node:events';\nimport {platform} from 'node:os';\nimport {pid} from 'node:process';\n\n/**\n * Central registry of message type names, which are used to identify\n * the payload in {@link Message} objects sent between processes. The\n * payloads themselves are implementation specific and defined in each\n * component; only the type name is reserved here to avoid collisions.\n *\n * Receiving logic can call {@link getMessage()} with the name of\n * the message of interest to filter messages to those of interest.\n */\nexport const MESSAGE_TYPES = {\n  handoff: 'handoff',\n  status: 'status',\n  subscribe: 'subscribe',\n  notify: 'notify',\n  ready: 'ready',\n  backupWatermarkUpdate: 'backupWatermakUpdate',\n} as const;\n\nexport type Message<Payload> = [keyof typeof MESSAGE_TYPES, Payload];\n\nfunction getMessage<M extends Message<unknown>>(\n  type: M[0],\n  data: unknown,\n): M[1] | null {\n  if (Array.isArray(data) && data.length === 2 && data[0] === type) {\n    return data[1] as M[1];\n  }\n  return null;\n}\n\nfunction onMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  return e.on('message', (data, sendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      handler(msg, sendHandle);\n    }\n  });\n}\n\nfunction onceMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  const listener = (data: unknown, sendHandle: SendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      e.off('message', listener);\n      handler(msg, sendHandle);\n    }\n  };\n  return e.on('message', listener);\n}\n\nexport interface Sender {\n  send<M extends Message<unknown>>(\n    message: M,\n    sendHandle?: SendHandle,\n    callback?: (error: Error | null) => void,\n  ): boolean;\n\n  kill(signal?: NodeJS.Signals): void;\n}\n\nexport interface Subprocess extends Sender, EventEmitter {\n  pid?: number | undefined;\n}\n\nexport interface Receiver extends EventEmitter {\n  /**\n   * The receiving side of {@link Sender.send()} that is a wrapper around\n   * {@link on}('message', ...) that invokes the `handler` for messages of\n   * the specified `type`.\n   */\n  onMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n\n  /**\n   * The receiving side of {@link Sender.send()} that behaves like\n   * {@link once}('message', ...) that invokes the `handler` for the next\n   * message of the specified `type` and then unsubscribes.\n   */\n  onceMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n}\n\nexport interface Worker extends Subprocess, Receiver {}\n\n/**\n * Adds the {@link Receiver.onMessageType()} and {@link Receiver.onceMessageType()}\n * methods to convert the given `EventEmitter` to a `Receiver`.\n */\nfunction wrap<P extends EventEmitter>(proc: P): P & Receiver {\n  return new Proxy(proc, {\n    get(target: P, prop: string | symbol, receiver: unknown) {\n      switch (prop) {\n        case 'onMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onMessageType(target, type, handler);\n            return receiver; // this\n          };\n        case 'onceMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onceMessageType(target, type, handler);\n            return receiver; // this\n          };\n      }\n      return Reflect.get(target, prop, receiver);\n    },\n  }) as P & Receiver;\n}\n\ntype Proc = Pick<ChildProcess, 'send' | 'kill' | 'pid'> & EventEmitter;\n\n/**\n * The parentWorker for forked processes, or `null` if the process was not forked.\n * (Analogous to the `parentPort: MessagePort | null` of the `\"workers\"` library).\n */\nexport const parentWorker: Worker | null = process.send\n  ? wrap(process as Proc)\n  : null;\n\nconst SINGLE_PROCESS = 'SINGLE_PROCESS';\nlet singleProcessOverride = false;\nexport function singleProcessMode(): boolean {\n  return singleProcessOverride || (process.env[SINGLE_PROCESS] ?? '0') !== '0';\n}\n\nexport function setSingleProcessMode(enabled: boolean = true): void {\n  singleProcessOverride = enabled;\n}\n\n/**\n * Determines whether a module loaded as a worker process entry point should\n * start its worker.\n *\n * Most workers are launched via {@link childWorker}, which in single-process\n * mode runs them in-process (no real fork) by invoking their exported\n * `runWorker` directly; those entry points must therefore *not* self-start in\n * single-process mode, or they would run twice.\n *\n * A worker launched via {@link forkChildWorker}, however, is *always* a real\n * forked OS process — even in single-process mode — and it inherits the\n * parent's `SINGLE_PROCESS` env. So {@link singleProcessMode} alone would\n * wrongly suppress its startup, leaving the parent to spin re-forking a child\n * that immediately exits. Such a forked child has a non-null\n * {@link parentWorker} (`process.send` is defined), which is the signal to\n * start regardless. A standalone direct launch (no parent, not single-process)\n * also starts.\n *\n * @param parent The entry point's {@link parentWorker} (non-null iff forked).\n * @param isSingleProcessMode The result of {@link singleProcessMode}.\n */\nexport function shouldStartWorker(\n  parent: Worker | null,\n  isSingleProcessMode: boolean,\n): boolean {\n  return parent !== null || !isSingleProcessMode;\n}\n\n/**\n *\n * @param modulePath Path to the module file, relative to zero-cache/src/, or an absolute file:// URL\n */\nexport function childWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  args = workerArgs(args);\n\n  if (singleProcessMode()) {\n    const [parent, child] = inProcChannel();\n    import(moduleUrl.href)\n      .then(async ({default: runWorker}) => {\n        try {\n          await runWorker(parent, env ?? process.env, ...args);\n          child.emit('close', 0);\n          return;\n        } catch (err) {\n          child.emit('error', err);\n          child.emit('close', -1);\n        }\n      })\n      .catch(err => child.emit('error', err));\n    return child;\n  }\n  return forkChildWorkerWithArgs(moduleUrl, env, args);\n}\n\nexport function forkChildWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  return forkChildWorkerWithArgs(moduleUrl, env, workerArgs(args));\n}\n\nfunction workerArgs(args: string[]): string[] {\n  return [...args, ...process.argv.slice(2)];\n}\n\nfunction forkChildWorkerWithArgs(\n  moduleUrl: URL,\n  env: NodeJS.ProcessEnv | undefined,\n  args: string[],\n): Worker {\n  const child = fork(moduleUrl, args, {\n    // For production / non-windows, set `detached` to `true` so that SIGINT is\n    // not automatically propagated and graceful shutdown happens as intended.\n    // For Win32, detached: true causes all subprocesses to open in separate\n    // terminals and breaks inter-process kill signals, so set it to false.\n    detached: platform() !== 'win32',\n    serialization: 'advanced', // use structured clone for IPC\n    env,\n  });\n  return wrap(child);\n}\n\n/**\n * Creates two connected `Worker` instances such that messages sent to one\n * via the {@link Worker.send()} method are received by the other's\n * `on('message', ...)` handler.\n *\n * This is analogous to the two `MessagePort`s of a `MessageChannel`, and\n * is useful for executing code written for inter-process communication\n * in a single process.\n */\nexport function inProcChannel(): [Worker, Worker] {\n  const worker1 = new EventEmitter();\n  const worker2 = new EventEmitter();\n\n  const sendTo =\n    (dest: EventEmitter) =>\n    (\n      message: Serializable,\n      sendHandle?: SendHandle,\n      callback?: (error: Error | null) => void,\n    ) => {\n      dest.emit('message', message, sendHandle);\n      if (callback) {\n        callback(null);\n      }\n      return true;\n    };\n\n  const kill =\n    (dest: EventEmitter) =>\n    (signal: NodeJS.Signals = 'SIGTERM') =>\n      dest.emit(signal, signal);\n\n  return [\n    wrap(\n      Object.assign(worker1, {send: sendTo(worker2), kill: kill(worker2), pid}),\n    ),\n    wrap(\n      Object.assign(worker2, {send: sendTo(worker1), kill: kill(worker1), pid}),\n    ),\n  ];\n}\n"],"mappings":";;;;;AA8BA,SAAS,WACP,MACA,MACa;CACb,IAAI,MAAM,QAAQ,IAAI,KAAK,KAAK,WAAW,KAAK,KAAK,OAAO,MAC1D,OAAO,KAAK;CAEd,OAAO;AACT;AAEA,SAAS,cACP,GACA,MACA,SACA;CACA,OAAO,EAAE,GAAG,YAAY,MAAM,eAAe;EAC3C,MAAM,MAAM,WAAW,MAAM,IAAI;EACjC,IAAI,KACF,QAAQ,KAAK,UAAU;CAE3B,CAAC;AACH;AAEA,SAAS,gBACP,GACA,MACA,SACA;CACA,MAAM,YAAY,MAAe,eAA2B;EAC1D,MAAM,MAAM,WAAW,MAAM,IAAI;EACjC,IAAI,KAAK;GACP,EAAE,IAAI,WAAW,QAAQ;GACzB,QAAQ,KAAK,UAAU;EACzB;CACF;CACA,OAAO,EAAE,GAAG,WAAW,QAAQ;AACjC;;;;;AA4CA,SAAS,KAA6B,MAAuB;CAC3D,OAAO,IAAI,MAAM,MAAM,EACrB,IAAI,QAAW,MAAuB,UAAmB;EACvD,QAAQ,MAAR;GACE,KAAK,iBACH,QACE,MACA,YACG;IACH,cAAc,QAAQ,MAAM,OAAO;IACnC,OAAO;GACT;GACF,KAAK,mBACH,QACE,MACA,YACG;IACH,gBAAgB,QAAQ,MAAM,OAAO;IACrC,OAAO;GACT;EACJ;EACA,OAAO,QAAQ,IAAI,QAAQ,MAAM,QAAQ;CAC3C,EACF,CAAC;AACH;;;;;AAQA,IAAa,eAA8B,QAAQ,OAC/C,KAAK,OAAe,IACpB;AAEJ,IAAM,iBAAiB;AACvB,IAAI,wBAAwB;AAC5B,SAAgB,oBAA6B;CAC3C,OAAO,0BAA0B,QAAQ,IAAI,mBAAmB,SAAS;AAC3E;;;;;AAsCA,SAAgB,YACd,WACA,KACA,GAAG,MACK;CACR,OAAO,WAAW,IAAI;CAEtB,IAAI,kBAAkB,GAAG;EACvB,MAAM,CAAC,QAAQ,SAAS,cAAc;EACtC,OAAO,UAAU,MACd,KAAK,OAAO,EAAC,SAAS,gBAAe;GACpC,IAAI;IACF,MAAM,UAAU,QAAQ,OAAO,QAAQ,KAAK,GAAG,IAAI;IACnD,MAAM,KAAK,SAAS,CAAC;IACrB;GACF,SAAS,KAAK;IACZ,MAAM,KAAK,SAAS,GAAG;IACvB,MAAM,KAAK,SAAS,EAAE;GACxB;EACF,CAAC,EACA,OAAM,QAAO,MAAM,KAAK,SAAS,GAAG,CAAC;EACxC,OAAO;CACT;CACA,OAAO,wBAAwB,WAAW,KAAK,IAAI;AACrD;AAUA,SAAS,WAAW,MAA0B;CAC5C,OAAO,CAAC,GAAG,MAAM,GAAG,QAAQ,KAAK,MAAM,CAAC,CAAC;AAC3C;AAEA,SAAS,wBACP,WACA,KACA,MACQ;CAUR,OAAO,KATO,KAAK,WAAW,MAAM;EAKlC,UAAU,SAAS,MAAM;EACzB,eAAe;EACf;CACF,CACY,CAAK;AACnB;;;;;;;;;;AAWA,SAAgB,gBAAkC;CAChD,MAAM,UAAU,IAAI,aAAa;CACjC,MAAM,UAAU,IAAI,aAAa;CAEjC,MAAM,UACH,UAEC,SACA,YACA,aACG;EACH,KAAK,KAAK,WAAW,SAAS,UAAU;EACxC,IAAI,UACF,SAAS,IAAI;EAEf,OAAO;CACT;CAEF,MAAM,QACH,UACA,SAAyB,cACxB,KAAK,KAAK,QAAQ,MAAM;CAE5B,OAAO,CACL,KACE,OAAO,OAAO,SAAS;EAAC,MAAM,OAAO,OAAO;EAAG,MAAM,KAAK,OAAO;EAAG;CAAG,CAAC,CAC1E,GACA,KACE,OAAO,OAAO,SAAS;EAAC,MAAM,OAAO,OAAO;EAAG,MAAM,KAAK,OAAO;EAAG;CAAG,CAAC,CAC1E,CACF;AACF"}
+{"version":3,"file":"processes.js","names":[],"sources":["../../../../../zero-cache/src/types/processes.ts"],"sourcesContent":["import {\n  type ChildProcess,\n  fork,\n  type SendHandle,\n  type Serializable,\n} from 'node:child_process';\nimport EventEmitter from 'node:events';\nimport {platform} from 'node:os';\nimport {pid} from 'node:process';\n\n/**\n * Central registry of message type names, which are used to identify\n * the payload in {@link Message} objects sent between processes. The\n * payloads themselves are implementation specific and defined in each\n * component; only the type name is reserved here to avoid collisions.\n *\n * Receiving logic can call {@link getMessage()} with the name of\n * the message of interest to filter messages to those of interest.\n */\nexport const MESSAGE_TYPES = {\n  handoff: 'handoff',\n  status: 'status',\n  clientGroupStatus: 'clientGroupStatus',\n  subscribe: 'subscribe',\n  notify: 'notify',\n  ready: 'ready',\n  backupWatermarkUpdate: 'backupWatermakUpdate',\n  profile: 'profile',\n  profileResponse: 'profileResponse',\n} as const;\n\nexport type ClientGroupStatus = {\n  readonly clientGroupID: string;\n  readonly active: boolean;\n  readonly generation?: number | undefined;\n};\n\nexport type ClientGroupStatusMessage = ['clientGroupStatus', ClientGroupStatus];\n\nexport type ProfileRequest = {\n  readonly id: string;\n  readonly durationMs: number;\n  readonly worker?: string | undefined;\n  readonly workerIndex?: number | undefined;\n};\n\nexport type ProfileResponse = {\n  readonly id: string;\n  readonly name: string;\n  readonly profile?: unknown | undefined;\n  readonly error?: string | undefined;\n};\n\nexport type ProfileMessage = ['profile', ProfileRequest];\nexport type ProfileResponseMessage = ['profileResponse', ProfileResponse];\n\nexport type Message<Payload> = [keyof typeof MESSAGE_TYPES, Payload];\n\nfunction getMessage<M extends Message<unknown>>(\n  type: M[0],\n  data: unknown,\n): M[1] | null {\n  if (Array.isArray(data) && data.length === 2 && data[0] === type) {\n    return data[1] as M[1];\n  }\n  return null;\n}\n\n/**\n * Subscribes the `handler` to messages of the given `type` and returns a\n * function that unsubscribes it. Use this (rather than\n * {@link Receiver.onMessageType()}) for handlers scoped to a request or\n * operation rather than to the lifetime of the {@link Worker}; the\n * `'message'` listener is otherwise retained by the Worker forever.\n */\nexport function subscribeToMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n): () => void {\n  const listener = (data: unknown, sendHandle?: SendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      handler(msg, sendHandle);\n    }\n  };\n  e.on('message', listener);\n  return () => {\n    e.off('message', listener);\n  };\n}\n\nfunction onMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  subscribeToMessageType(e, type, handler);\n  return e;\n}\n\nfunction onceMessageType<M extends Message<unknown>>(\n  e: EventEmitter,\n  type: M[0],\n  handler: (msg: M[1], sendHandle?: SendHandle) => void,\n) {\n  const listener = (data: unknown, sendHandle: SendHandle) => {\n    const msg = getMessage(type, data);\n    if (msg) {\n      e.off('message', listener);\n      handler(msg, sendHandle);\n    }\n  };\n  return e.on('message', listener);\n}\n\nexport interface Sender {\n  send<M extends Message<unknown>>(\n    message: M,\n    sendHandle?: SendHandle,\n    callback?: (error: Error | null) => void,\n  ): boolean;\n\n  kill(signal?: NodeJS.Signals): void;\n}\n\nexport interface Subprocess extends Sender, EventEmitter {\n  pid?: number | undefined;\n}\n\nexport interface Receiver extends EventEmitter {\n  /**\n   * The receiving side of {@link Sender.send()} that is a wrapper around\n   * {@link on}('message', ...) that invokes the `handler` for messages of\n   * the specified `type`.\n   */\n  onMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n\n  /**\n   * The receiving side of {@link Sender.send()} that behaves like\n   * {@link once}('message', ...) that invokes the `handler` for the next\n   * message of the specified `type` and then unsubscribes.\n   */\n  onceMessageType<M extends Message<unknown>>(\n    type: M[0],\n    handler: (msg: M[1], sendHandle?: SendHandle) => void,\n  ): this;\n}\n\nexport interface Worker extends Subprocess, Receiver {}\n\n/**\n * Adds the {@link Receiver.onMessageType()} and {@link Receiver.onceMessageType()}\n * methods to convert the given `EventEmitter` to a `Receiver`.\n */\nfunction wrap<P extends EventEmitter>(proc: P): P & Receiver {\n  return new Proxy(proc, {\n    get(target: P, prop: string | symbol, receiver: unknown) {\n      switch (prop) {\n        case 'onMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onMessageType(target, type, handler);\n            return receiver; // this\n          };\n        case 'onceMessageType':\n          return (\n            type: keyof typeof MESSAGE_TYPES,\n            handler: (msg: unknown, sendHandle?: SendHandle) => void,\n          ) => {\n            onceMessageType(target, type, handler);\n            return receiver; // this\n          };\n      }\n      return Reflect.get(target, prop, receiver);\n    },\n  }) as P & Receiver;\n}\n\ntype Proc = Pick<ChildProcess, 'send' | 'kill' | 'pid'> & EventEmitter;\n\n/**\n * The parentWorker for forked processes, or `null` if the process was not forked.\n * (Analogous to the `parentPort: MessagePort | null` of the `\"workers\"` library).\n */\nexport const parentWorker: Worker | null = process.send\n  ? wrap(process as Proc)\n  : null;\n\nconst SINGLE_PROCESS = 'SINGLE_PROCESS';\nlet singleProcessOverride = false;\nexport function singleProcessMode(): boolean {\n  return singleProcessOverride || (process.env[SINGLE_PROCESS] ?? '0') !== '0';\n}\n\nexport function setSingleProcessMode(enabled: boolean = true): void {\n  singleProcessOverride = enabled;\n}\n\n/**\n * Determines whether a module loaded as a worker process entry point should\n * start its worker.\n *\n * Most workers are launched via {@link childWorker}, which in single-process\n * mode runs them in-process (no real fork) by invoking their exported\n * `runWorker` directly; those entry points must therefore *not* self-start in\n * single-process mode, or they would run twice.\n *\n * A worker launched via {@link forkChildWorker}, however, is *always* a real\n * forked OS process — even in single-process mode — and it inherits the\n * parent's `SINGLE_PROCESS` env. So {@link singleProcessMode} alone would\n * wrongly suppress its startup, leaving the parent to spin re-forking a child\n * that immediately exits. Such a forked child has a non-null\n * {@link parentWorker} (`process.send` is defined), which is the signal to\n * start regardless. A standalone direct launch (no parent, not single-process)\n * also starts.\n *\n * @param parent The entry point's {@link parentWorker} (non-null iff forked).\n * @param isSingleProcessMode The result of {@link singleProcessMode}.\n */\nexport function shouldStartWorker(\n  parent: Worker | null,\n  isSingleProcessMode: boolean,\n): boolean {\n  return parent !== null || !isSingleProcessMode;\n}\n\n/**\n *\n * @param modulePath Path to the module file, relative to zero-cache/src/, or an absolute file:// URL\n */\nexport function childWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  args = workerArgs(args);\n\n  if (singleProcessMode()) {\n    const [parent, child] = inProcChannel();\n    import(moduleUrl.href)\n      .then(async ({default: runWorker}) => {\n        try {\n          await runWorker(parent, env ?? process.env, ...args);\n          child.emit('close', 0);\n          return;\n        } catch (err) {\n          child.emit('error', err);\n          child.emit('close', -1);\n        }\n      })\n      .catch(err => child.emit('error', err));\n    return child;\n  }\n  return forkChildWorkerWithArgs(moduleUrl, env, args);\n}\n\nexport function forkChildWorker(\n  moduleUrl: URL,\n  env?: NodeJS.ProcessEnv,\n  ...args: string[]\n): Worker {\n  return forkChildWorkerWithArgs(moduleUrl, env, workerArgs(args));\n}\n\nfunction workerArgs(args: string[]): string[] {\n  return [...args, ...process.argv.slice(2)];\n}\n\nfunction forkChildWorkerWithArgs(\n  moduleUrl: URL,\n  env: NodeJS.ProcessEnv | undefined,\n  args: string[],\n): Worker {\n  const child = fork(moduleUrl, args, {\n    // For production / non-windows, set `detached` to `true` so that SIGINT is\n    // not automatically propagated and graceful shutdown happens as intended.\n    // For Win32, detached: true causes all subprocesses to open in separate\n    // terminals and breaks inter-process kill signals, so set it to false.\n    detached: platform() !== 'win32',\n    serialization: 'advanced', // use structured clone for IPC\n    env,\n  });\n  return wrap(child);\n}\n\n/**\n * Creates two connected `Worker` instances such that messages sent to one\n * via the {@link Worker.send()} method are received by the other's\n * `on('message', ...)` handler.\n *\n * This is analogous to the two `MessagePort`s of a `MessageChannel`, and\n * is useful for executing code written for inter-process communication\n * in a single process.\n */\nexport function inProcChannel(): [Worker, Worker] {\n  const worker1 = new EventEmitter();\n  const worker2 = new EventEmitter();\n\n  const sendTo =\n    (dest: EventEmitter) =>\n    (\n      message: Serializable,\n      sendHandle?: SendHandle,\n      callback?: (error: Error | null) => void,\n    ) => {\n      dest.emit('message', message, sendHandle);\n      if (callback) {\n        callback(null);\n      }\n      return true;\n    };\n\n  const kill =\n    (dest: EventEmitter) =>\n    (signal: NodeJS.Signals = 'SIGTERM') =>\n      dest.emit(signal, signal);\n\n  return [\n    wrap(\n      Object.assign(worker1, {send: sendTo(worker2), kill: kill(worker2), pid}),\n    ),\n    wrap(\n      Object.assign(worker2, {send: sendTo(worker1), kill: kill(worker1), pid}),\n    ),\n  ];\n}\n\n/**\n * Creates a {@link Worker} facade that broadcasts `send()` to all provided\n * workers and aggregates their `'message'` events into one stream.\n *\n * This is useful for code that expects a single Worker for IPC (e.g.\n * `handleProfzRequest`) but needs to reach multiple child workers.\n */\nexport function broadcastWorker(workers: Worker[]): Worker {\n  const emitter = new EventEmitter();\n\n  for (const w of workers) {\n    w.on('message', (message: Serializable, sendHandle?: SendHandle) =>\n      emitter.emit('message', message, sendHandle),\n    );\n  }\n\n  const send = <M extends Message<unknown>>(\n    message: M,\n    sendHandle?: SendHandle,\n    callback?: (error: Error | null) => void,\n  ) => {\n    for (const w of workers) {\n      w.send(message, sendHandle);\n    }\n    if (callback) {\n      callback(null);\n    }\n    return true;\n  };\n\n  const kill = (signal: NodeJS.Signals = 'SIGTERM') => {\n    for (const w of workers) {\n      w.kill(signal);\n    }\n  };\n\n  return wrap(Object.assign(emitter, {send, kill, pid}));\n}\n"],"mappings":"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"}

package/out/zero-cache/src/types/profiler.d.ts

@@ -1,4 +1,5 @@
 import type { LogContext } from '@rocicorp/logger';
+import type { Worker } from './processes.ts';
 /**
  * Convenience wrapper around a `node:inspector` {@link Session} for
  * optionally taking cpu profiles.
@@ -8,6 +9,17 @@ export declare class CpuProfiler {
     static connect(): Promise<CpuProfiler>;
     private constructor();
     start(): Promise<void>;
+    /**
+     * Captures a CPU profile for the specified duration (in milliseconds)
+     * and returns the V8 profile object.
+     */
+    static profile(durationMs: number): Promise<unknown>;
+    stop(): Promise<unknown>;
     stopAndDispose(lc: LogContext, filename: string): Promise<void>;
 }
+/**
+ * Registers an IPC handler on `parent` to capture a CPU profile when
+ * requested, sending back the resulting V8 profile.
+ */
+export declare function installProfileHandler(parent: Worker | null, workerName: string, workerIndex?: number | undefined): void;
 //# sourceMappingURL=profiler.d.ts.map

package/out/zero-cache/src/types/profiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiler.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/profiler.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AAEjD;;;GAGG;AACH,qBAAa,WAAW;;IACtB,OAAa,OAAO,yBAKnB;IAID,OAAO,eAEN;IAEK,KAAK,kBAEV;IAEK,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAMpD;CACF"}
+{"version":3,"file":"profiler.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/profiler.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAiB,MAAM,EAAC,MAAM,gBAAgB,CAAC;AAE3D;;;GAGG;AACH,qBAAa,WAAW;;IACtB,OAAa,OAAO,yBAKnB;IAID,OAAO,eAEN;IAEK,KAAK,kBAEV;IAED;;;OAGG;IACH,OAAa,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKzD;IAEK,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAK7B;IAEK,cAAc,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAMpD;CACF;AAID;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,GAC/B,IAAI,CA6BN"}

package/out/zero-cache/src/types/profiler.js

@@ -21,6 +21,22 @@ var CpuProfiler = class CpuProfiler {
 	async start() {
 		await this.#session.post("Profiler.start");
 	}
+	/**
+	* Captures a CPU profile for the specified duration (in milliseconds)
+	* and returns the V8 profile object.
+	*/
+	static async profile(durationMs) {
+		const profiler = await CpuProfiler.connect();
+		await profiler.start();
+		await new Promise((resolve) => setTimeout(resolve, durationMs));
+		return await profiler.stop();
+	}
+	async stop() {
+		const { profile } = await this.#session.post("Profiler.stop");
+		await this.#session.post("Profiler.disable");
+		this.#session.disconnect();
+		return profile;
+	}
 	async stopAndDispose(lc, filename) {
 		const { profile } = await this.#session.post("Profiler.stop");
 		const path = join(tmpdir(), `${filename}.cpuprofile`);
@@ -29,7 +45,36 @@ var CpuProfiler = class CpuProfiler {
 		this.#session.disconnect();
 	}
 };
+var WORKER_INDEX_SUFFIX = /-\d+$/;
+/**
+* Registers an IPC handler on `parent` to capture a CPU profile when
+* requested, sending back the resulting V8 profile.
+*/
+function installProfileHandler(parent, workerName, workerIndex) {
+	if (!parent) return;
+	parent.onMessageType("profile", async (req) => {
+		if (req.worker !== void 0) {
+			const baseName = workerName.replace(WORKER_INDEX_SUFFIX, "");
+			if (!(req.worker === workerName || req.worker === baseName)) return;
+			if (req.workerIndex !== void 0 && workerIndex !== void 0 && req.workerIndex !== workerIndex) return;
+		}
+		try {
+			const profile = await CpuProfiler.profile(req.durationMs);
+			parent.send(["profileResponse", {
+				id: req.id,
+				name: workerName,
+				profile
+			}]);
+		} catch (err) {
+			parent.send(["profileResponse", {
+				id: req.id,
+				name: workerName,
+				error: String(err)
+			}]);
+		}
+	});
+}
 //#endregion
-export { CpuProfiler };
+export { CpuProfiler, installProfileHandler };
 
 //# sourceMappingURL=profiler.js.map

package/out/zero-cache/src/types/profiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"profiler.js","names":["#session"],"sources":["../../../../../zero-cache/src/types/profiler.ts"],"sourcesContent":["import {writeFile} from 'node:fs/promises';\nimport {Session} from 'node:inspector/promises';\nimport {tmpdir} from 'node:os';\nimport {join} from 'node:path';\nimport type {LogContext} from '@rocicorp/logger';\n\n/**\n * Convenience wrapper around a `node:inspector` {@link Session} for\n * optionally taking cpu profiles.\n */\nexport class CpuProfiler {\n  static async connect() {\n    const session = new Session();\n    session.connect();\n    await session.post('Profiler.enable');\n    return new CpuProfiler(session);\n  }\n\n  readonly #session;\n\n  private constructor(session: Session) {\n    this.#session = session;\n  }\n\n  async start() {\n    await this.#session.post('Profiler.start');\n  }\n\n  async stopAndDispose(lc: LogContext, filename: string) {\n    const {profile} = await this.#session.post('Profiler.stop');\n    const path = join(tmpdir(), `${filename}.cpuprofile`);\n    await writeFile(path, JSON.stringify(profile));\n    lc.info?.(`wrote cpu profile to ${path}`);\n    this.#session.disconnect();\n  }\n}\n"],"mappings":";;;;;;;;;AAUA,IAAa,cAAb,MAAa,YAAY;CACvB,aAAa,UAAU;EACrB,MAAM,UAAU,IAAI,QAAQ;EAC5B,QAAQ,QAAQ;EAChB,MAAM,QAAQ,KAAK,iBAAiB;EACpC,OAAO,IAAI,YAAY,OAAO;CAChC;CAEA;CAEA,YAAoB,SAAkB;EACpC,KAAKA,WAAW;CAClB;CAEA,MAAM,QAAQ;EACZ,MAAM,KAAKA,SAAS,KAAK,gBAAgB;CAC3C;CAEA,MAAM,eAAe,IAAgB,UAAkB;EACrD,MAAM,EAAC,YAAW,MAAM,KAAKA,SAAS,KAAK,eAAe;EAC1D,MAAM,OAAO,KAAK,OAAO,GAAG,GAAG,SAAS,YAAY;EACpD,MAAM,UAAU,MAAM,KAAK,UAAU,OAAO,CAAC;EAC7C,GAAG,OAAO,wBAAwB,MAAM;EACxC,KAAKA,SAAS,WAAW;CAC3B;AACF"}
+{"version":3,"file":"profiler.js","names":["#session"],"sources":["../../../../../zero-cache/src/types/profiler.ts"],"sourcesContent":["import {writeFile} from 'node:fs/promises';\nimport {Session} from 'node:inspector/promises';\nimport {tmpdir} from 'node:os';\nimport {join} from 'node:path';\nimport type {LogContext} from '@rocicorp/logger';\nimport type {ProfileMessage, Worker} from './processes.ts';\n\n/**\n * Convenience wrapper around a `node:inspector` {@link Session} for\n * optionally taking cpu profiles.\n */\nexport class CpuProfiler {\n  static async connect() {\n    const session = new Session();\n    session.connect();\n    await session.post('Profiler.enable');\n    return new CpuProfiler(session);\n  }\n\n  readonly #session;\n\n  private constructor(session: Session) {\n    this.#session = session;\n  }\n\n  async start() {\n    await this.#session.post('Profiler.start');\n  }\n\n  /**\n   * Captures a CPU profile for the specified duration (in milliseconds)\n   * and returns the V8 profile object.\n   */\n  static async profile(durationMs: number): Promise<unknown> {\n    const profiler = await CpuProfiler.connect();\n    await profiler.start();\n    await new Promise(resolve => setTimeout(resolve, durationMs));\n    return await profiler.stop();\n  }\n\n  async stop(): Promise<unknown> {\n    const {profile} = await this.#session.post('Profiler.stop');\n    await this.#session.post('Profiler.disable');\n    this.#session.disconnect();\n    return profile;\n  }\n\n  async stopAndDispose(lc: LogContext, filename: string) {\n    const {profile} = await this.#session.post('Profiler.stop');\n    const path = join(tmpdir(), `${filename}.cpuprofile`);\n    await writeFile(path, JSON.stringify(profile));\n    lc.info?.(`wrote cpu profile to ${path}`);\n    this.#session.disconnect();\n  }\n}\n\nconst WORKER_INDEX_SUFFIX = /-\\d+$/;\n\n/**\n * Registers an IPC handler on `parent` to capture a CPU profile when\n * requested, sending back the resulting V8 profile.\n */\nexport function installProfileHandler(\n  parent: Worker | null,\n  workerName: string,\n  workerIndex?: number | undefined,\n): void {\n  if (!parent) {\n    return;\n  }\n  parent.onMessageType<ProfileMessage>('profile', async req => {\n    if (req.worker !== undefined) {\n      const baseName = workerName.replace(WORKER_INDEX_SUFFIX, '');\n      const matchesName = req.worker === workerName || req.worker === baseName;\n      if (!matchesName) {\n        return;\n      }\n      if (\n        req.workerIndex !== undefined &&\n        workerIndex !== undefined &&\n        req.workerIndex !== workerIndex\n      ) {\n        return;\n      }\n    }\n    try {\n      const profile = await CpuProfiler.profile(req.durationMs);\n      parent.send(['profileResponse', {id: req.id, name: workerName, profile}]);\n    } catch (err) {\n      parent.send([\n        'profileResponse',\n        {id: req.id, name: workerName, error: String(err)},\n      ]);\n    }\n  });\n}\n"],"mappings":";;;;;;;;;AAWA,IAAa,cAAb,MAAa,YAAY;CACvB,aAAa,UAAU;EACrB,MAAM,UAAU,IAAI,QAAQ;EAC5B,QAAQ,QAAQ;EAChB,MAAM,QAAQ,KAAK,iBAAiB;EACpC,OAAO,IAAI,YAAY,OAAO;CAChC;CAEA;CAEA,YAAoB,SAAkB;EACpC,KAAKA,WAAW;CAClB;CAEA,MAAM,QAAQ;EACZ,MAAM,KAAKA,SAAS,KAAK,gBAAgB;CAC3C;;;;;CAMA,aAAa,QAAQ,YAAsC;EACzD,MAAM,WAAW,MAAM,YAAY,QAAQ;EAC3C,MAAM,SAAS,MAAM;EACrB,MAAM,IAAI,SAAQ,YAAW,WAAW,SAAS,UAAU,CAAC;EAC5D,OAAO,MAAM,SAAS,KAAK;CAC7B;CAEA,MAAM,OAAyB;EAC7B,MAAM,EAAC,YAAW,MAAM,KAAKA,SAAS,KAAK,eAAe;EAC1D,MAAM,KAAKA,SAAS,KAAK,kBAAkB;EAC3C,KAAKA,SAAS,WAAW;EACzB,OAAO;CACT;CAEA,MAAM,eAAe,IAAgB,UAAkB;EACrD,MAAM,EAAC,YAAW,MAAM,KAAKA,SAAS,KAAK,eAAe;EAC1D,MAAM,OAAO,KAAK,OAAO,GAAG,GAAG,SAAS,YAAY;EACpD,MAAM,UAAU,MAAM,KAAK,UAAU,OAAO,CAAC;EAC7C,GAAG,OAAO,wBAAwB,MAAM;EACxC,KAAKA,SAAS,WAAW;CAC3B;AACF;AAEA,IAAM,sBAAsB;;;;;AAM5B,SAAgB,sBACd,QACA,YACA,aACM;CACN,IAAI,CAAC,QACH;CAEF,OAAO,cAA8B,WAAW,OAAM,QAAO;EAC3D,IAAI,IAAI,WAAW,KAAA,GAAW;GAC5B,MAAM,WAAW,WAAW,QAAQ,qBAAqB,EAAE;GAE3D,IAAI,EADgB,IAAI,WAAW,cAAc,IAAI,WAAW,WAE9D;GAEF,IACE,IAAI,gBAAgB,KAAA,KACpB,gBAAgB,KAAA,KAChB,IAAI,gBAAgB,aAEpB;EAEJ;EACA,IAAI;GACF,MAAM,UAAU,MAAM,YAAY,QAAQ,IAAI,UAAU;GACxD,OAAO,KAAK,CAAC,mBAAmB;IAAC,IAAI,IAAI;IAAI,MAAM;IAAY;GAAO,CAAC,CAAC;EAC1E,SAAS,KAAK;GACZ,OAAO,KAAK,CACV,mBACA;IAAC,IAAI,IAAI;IAAI,MAAM;IAAY,OAAO,OAAO,GAAG;GAAC,CACnD,CAAC;EACH;CACF,CAAC;AACH"}

package/out/zero-cache/src/types/row-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"row-key.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/row-key.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,SAAS,EAAC,MAAM,oCAAoC,CAAC;AAG7E,MAAM,MAAM,UAAU,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC;AACpD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;AAC9D,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEzD,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AAI9E,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC;AACjC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAClC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAkB7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAQD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,GAAG,MAAM,CAQ7C;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,KAAK,GAAG,MAAM,CAU3C"}
+{"version":3,"file":"row-key.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/row-key.ts"],"names":[],"mappings":"AACA,OAAO,EAAY,KAAK,SAAS,EAAC,MAAM,oCAAoC,CAAC;AAI7E,MAAM,MAAM,UAAU,GAAG;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC;AACpD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;AAC9D,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEzD,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AAI9E,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC;AACjC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAClC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAkB7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAQD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,KAAK,GAAG,MAAM,CAE7C;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,KAAK,GAAG,MAAM,CAE3C"}

package/out/zero-cache/src/types/row-key.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../shared/src/asserts.js";
+import { getOrInsertComputed } from "../../../shared/src/map.js";
 import "../../../shared/src/hash.js";
 import { stringify } from "../../../shared/src/bigint-json.js";
 //#region ../zero-cache/src/types/row-key.ts
@@ -34,15 +35,14 @@ var rowIDStrings = /* @__PURE__ */ new WeakMap();
 * length.
 */
 function rowIDString(id) {
-	let val = rowIDStrings.get(id);
-	if (val) return val;
-	val = stringify([
+	return getOrInsertComputed(rowIDStrings, id, rowIDStringUncached);
+}
+function rowIDStringUncached(id) {
+	return stringify([
 		id.schema,
 		id.table,
 		...tuples(id.rowKey)
 	]);
-	rowIDStrings.set(id, val);
-	return val;
 }
 //#endregion
 export { normalizedKeyOrder, rowIDString };

package/out/zero-cache/src/types/row-key.js.map

@@ -1 +1 @@
-{"version":3,"file":"row-key.js","names":[],"sources":["../../../../../zero-cache/src/types/row-key.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {stringify, type JSONValue} from '../../../shared/src/bigint-json.ts';\nimport {h128} from '../../../shared/src/hash.ts';\n\nexport type ColumnType = {readonly typeOid: number};\nexport type RowKeyType = Readonly<Record<string, ColumnType>>;\nexport type RowKey = Readonly<Record<string, JSONValue>>;\n\nexport type RowID = Readonly<{schema: string; table: string; rowKey: RowKey}>;\n\n// Aliased for documentation purposes when dealing with full rows vs row keys.\n// The actual structure of the objects is the same.\nexport type RowType = RowKeyType;\nexport type RowValue = RowKey;\n\n/**\n * Returns the `RowKey` such that key iteration produces a sorted sequence. If the\n * keys are already sorted, the input is returned as is.\n *\n * Note that the value type is parameterized as `V` so that this method can be used\n * for both (pg) RowKeys and LiteRowKeys.\n */\nexport function normalizedKeyOrder<V>(\n  rowKey: Readonly<Record<string, V>>,\n): Readonly<Record<string, V>> {\n  let last = '';\n  let empty = true;\n  for (const col in rowKey) {\n    empty = false;\n    if (last > col) {\n      const entries = Object.entries(rowKey).sort(([a], [b]) =>\n        a < b ? -1 : a > b ? 1 : 0,\n      );\n      assert(entries.length > 0, 'empty row key');\n      return Object.fromEntries(entries);\n    }\n    last = col;\n  }\n  assert(!empty, 'empty row key');\n  // This case iterates over columns and avoids object allocations, which is\n  // expected to be the common case (e.g. single column key).\n  return rowKey;\n}\n\n/**\n * Returns a normalized string suitable for representing a row key in a form\n * that can be used as a Map key.\n */\nexport function rowKeyString(key: RowKey): string {\n  return stringify(tuples(key));\n}\n\nfunction tuples(key: RowKey) {\n  return Object.entries(normalizedKeyOrder(key)).flat();\n}\n\nconst rowIDStrings = new WeakMap<RowID, string>();\n\n/**\n * A normalized string representation of a {@link RowID} suitable to use\n * as a Map key. Use {@link rowIDHash} if you need string keys of bounded\n * length.\n */\nexport function rowIDString(id: RowID): string {\n  let val = rowIDStrings.get(id);\n  if (val) {\n    return val;\n  }\n  val = stringify([id.schema, id.table, ...tuples(id.rowKey)]);\n  rowIDStrings.set(id, val);\n  return val;\n}\n\nconst rowIDHashes = new WeakMap<RowID, string>();\n\n/**\n * A RowIDHash is a 128-bit column-order-agnostic hash of the schema, table name, and\n * column name / value tuples of a row key. It serves as a compact identifier for\n * a row in the database that:\n *\n * * is guaranteed to fit within the constraints of the CVR store (Durable Object\n *   storage keys cannot exceed 2KiB)\n * * can be used to compactly encode (and lookup) the rows of query results for CVR\n *   bookkeeping.\n *\n * The hash is encoded in `base36`, with the maximum 128-bit value being 25 characters long.\n */\nexport function rowIDHash(id: RowID): string {\n  let hash = rowIDHashes.get(id);\n  if (hash) {\n    return hash;\n  }\n\n  const str = rowIDString(id);\n  hash = h128(str).toString(36);\n  rowIDHashes.set(id, hash);\n  return hash;\n}\n"],"mappings":";;;;;;;;;;;AAsBA,SAAgB,mBACd,QAC6B;CAC7B,IAAI,OAAO;CACX,IAAI,QAAQ;CACZ,KAAK,MAAM,OAAO,QAAQ;EACxB,QAAQ;EACR,IAAI,OAAO,KAAK;GACd,MAAM,UAAU,OAAO,QAAQ,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,OACjD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAC3B;GACA,OAAO,QAAQ,SAAS,GAAG,eAAe;GAC1C,OAAO,OAAO,YAAY,OAAO;EACnC;EACA,OAAO;CACT;CACA,OAAO,CAAC,OAAO,eAAe;CAG9B,OAAO;AACT;AAUA,SAAS,OAAO,KAAa;CAC3B,OAAO,OAAO,QAAQ,mBAAmB,GAAG,CAAC,EAAE,KAAK;AACtD;AAEA,IAAM,+BAAe,IAAI,QAAuB;;;;;;AAOhD,SAAgB,YAAY,IAAmB;CAC7C,IAAI,MAAM,aAAa,IAAI,EAAE;CAC7B,IAAI,KACF,OAAO;CAET,MAAM,UAAU;EAAC,GAAG;EAAQ,GAAG;EAAO,GAAG,OAAO,GAAG,MAAM;CAAC,CAAC;CAC3D,aAAa,IAAI,IAAI,GAAG;CACxB,OAAO;AACT"}
+{"version":3,"file":"row-key.js","names":[],"sources":["../../../../../zero-cache/src/types/row-key.ts"],"sourcesContent":["import {assert} from '../../../shared/src/asserts.ts';\nimport {stringify, type JSONValue} from '../../../shared/src/bigint-json.ts';\nimport {h128} from '../../../shared/src/hash.ts';\nimport {getOrInsertComputed} from '../../../shared/src/map.ts';\n\nexport type ColumnType = {readonly typeOid: number};\nexport type RowKeyType = Readonly<Record<string, ColumnType>>;\nexport type RowKey = Readonly<Record<string, JSONValue>>;\n\nexport type RowID = Readonly<{schema: string; table: string; rowKey: RowKey}>;\n\n// Aliased for documentation purposes when dealing with full rows vs row keys.\n// The actual structure of the objects is the same.\nexport type RowType = RowKeyType;\nexport type RowValue = RowKey;\n\n/**\n * Returns the `RowKey` such that key iteration produces a sorted sequence. If the\n * keys are already sorted, the input is returned as is.\n *\n * Note that the value type is parameterized as `V` so that this method can be used\n * for both (pg) RowKeys and LiteRowKeys.\n */\nexport function normalizedKeyOrder<V>(\n  rowKey: Readonly<Record<string, V>>,\n): Readonly<Record<string, V>> {\n  let last = '';\n  let empty = true;\n  for (const col in rowKey) {\n    empty = false;\n    if (last > col) {\n      const entries = Object.entries(rowKey).sort(([a], [b]) =>\n        a < b ? -1 : a > b ? 1 : 0,\n      );\n      assert(entries.length > 0, 'empty row key');\n      return Object.fromEntries(entries);\n    }\n    last = col;\n  }\n  assert(!empty, 'empty row key');\n  // This case iterates over columns and avoids object allocations, which is\n  // expected to be the common case (e.g. single column key).\n  return rowKey;\n}\n\n/**\n * Returns a normalized string suitable for representing a row key in a form\n * that can be used as a Map key.\n */\nexport function rowKeyString(key: RowKey): string {\n  return stringify(tuples(key));\n}\n\nfunction tuples(key: RowKey) {\n  return Object.entries(normalizedKeyOrder(key)).flat();\n}\n\nconst rowIDStrings = new WeakMap<RowID, string>();\n\n/**\n * A normalized string representation of a {@link RowID} suitable to use\n * as a Map key. Use {@link rowIDHash} if you need string keys of bounded\n * length.\n */\nexport function rowIDString(id: RowID): string {\n  return getOrInsertComputed(rowIDStrings, id, rowIDStringUncached);\n}\n\nfunction rowIDStringUncached(id: RowID): string {\n  return stringify([id.schema, id.table, ...tuples(id.rowKey)]);\n}\n\nconst rowIDHashes = new WeakMap<RowID, string>();\n\n/**\n * A RowIDHash is a 128-bit column-order-agnostic hash of the schema, table name, and\n * column name / value tuples of a row key. It serves as a compact identifier for\n * a row in the database that:\n *\n * * is guaranteed to fit within the constraints of the CVR store (Durable Object\n *   storage keys cannot exceed 2KiB)\n * * can be used to compactly encode (and lookup) the rows of query results for CVR\n *   bookkeeping.\n *\n * The hash is encoded in `base36`, with the maximum 128-bit value being 25 characters long.\n */\nexport function rowIDHash(id: RowID): string {\n  return getOrInsertComputed(rowIDHashes, id, rowIDHashUncached);\n}\n\nfunction rowIDHashUncached(id: RowID): string {\n  return h128(rowIDString(id)).toString(36);\n}\n"],"mappings":";;;;;;;;;;;;AAuBA,SAAgB,mBACd,QAC6B;CAC7B,IAAI,OAAO;CACX,IAAI,QAAQ;CACZ,KAAK,MAAM,OAAO,QAAQ;EACxB,QAAQ;EACR,IAAI,OAAO,KAAK;GACd,MAAM,UAAU,OAAO,QAAQ,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,OACjD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAC3B;GACA,OAAO,QAAQ,SAAS,GAAG,eAAe;GAC1C,OAAO,OAAO,YAAY,OAAO;EACnC;EACA,OAAO;CACT;CACA,OAAO,CAAC,OAAO,eAAe;CAG9B,OAAO;AACT;AAUA,SAAS,OAAO,KAAa;CAC3B,OAAO,OAAO,QAAQ,mBAAmB,GAAG,CAAC,EAAE,KAAK;AACtD;AAEA,IAAM,+BAAe,IAAI,QAAuB;;;;;;AAOhD,SAAgB,YAAY,IAAmB;CAC7C,OAAO,oBAAoB,cAAc,IAAI,mBAAmB;AAClE;AAEA,SAAS,oBAAoB,IAAmB;CAC9C,OAAO,UAAU;EAAC,GAAG;EAAQ,GAAG;EAAO,GAAG,OAAO,GAAG,MAAM;CAAC,CAAC;AAC9D"}

package/out/zero-cache/src/types/streams.d.ts

@@ -34,13 +34,34 @@ export type Source<T> = AsyncIterable<T> & {
         value: T;
         consumed: () => void;
     }> | undefined;
+    /**
+     * Pipelined batching support: eagerly drains available queued messages up to `maxBatch`.
+     */
+    pipelineBatched?: ((maxBatch?: number) => AsyncIterable<{
+        values: T[];
+        consumed: () => void;
+    }> | undefined) | undefined;
 };
 export type Sink<T> = {
     push(message: T): void;
 };
+/**
+ * Utility method for reading the first items from a {@link Source} and passing
+ * the `rest` to a separate consumer. The caller should call `head.next()` to
+ * pull items out of the Source, but should not call the
+ * {@link AsyncIterator.return()} method, as that will cancel the Source.
+ */
+export declare function readHead<T>(source: Source<T>): {
+    head: AsyncIterator<T, T, T>;
+    rest: Source<T>;
+};
 /**
  * Back-pressure-aware transformation of a WebSocket into
  * upstream and downstream {@link Subscription} objects.
+ *
+ * This is used for connections with external servers
+ * (i.e. custom change sources). For inter-zero-cache communication,
+ * see {@link streamInternal}.
  */
 export declare function stream<In extends JSONValue, Out extends JSONValue>(lc: LogContext, ws: WebSocket, inSchema: v.Type<In>, outOptions?: Options<Out>, inOptions?: Options<In>, streamOptions?: DuplexOptions): {
     outstream: Sink<Out>;
@@ -58,16 +79,37 @@ export type Sized<T> = {
     data: T;
     size: number;
 };
-export declare function streamOut<T extends JSONValue>(lc: LogContext, source: Source<T>, sink: WebSocket): Promise<void>;
+export type StreamOutOptions = {
+    batched?: boolean | undefined;
+    maxBatchSize?: number | undefined;
+};
+export type PreSerialized = {
+    readonly payload: Buffer;
+    readonly byteLength: number;
+};
+export declare function isPreSerialized(val: unknown): val is PreSerialized;
+/**
+ * Establishes a bidirectional stream over an internal zero-cache to zero-cache
+ * WebSocket. Both peers call this: each may send an outbound {@link Source}
+ * (`outSource`) and receives an inbound {@link Source} (the return value).
+ * Transport-level `{id, msg}` / `{ack}` framing is multiplexed in both
+ * directions over the single socket.
+ *
+ * `inSchema` validates inbound application frames; it may be omitted by a peer
+ * that expects no inbound application messages (any that arrive are a protocol
+ * error).
+ */
+export declare function streamInternal<In extends JSONValue, Out extends JSONValue = JSONValue>(lc: LogContext, ws: WebSocket, inSchema: v.Type<In> | undefined, outSource?: Source<Out>, options?: StreamOutOptions): Promise<Source<In>>;
 /**
- * Streams out a `Source` for which messages are already stringified JSON.
+ * {@link streamInternal} whose outbound `Source` carries messages that are
+ * already stringified JSON or pre-serialized Buffers.
  */
-export declare function streamOutStringified(lc: LogContext, source: Source<string>, sink: WebSocket): Promise<void>;
-export declare function streamIn<T extends JSONValue>(lc: LogContext, source: WebSocket, schema: v.Type<T>): Promise<Source<T>>;
+export declare function streamInternalStringified<In extends JSONValue>(lc: LogContext, ws: WebSocket, inSchema: v.Type<In> | undefined, outSource?: Source<string | PreSerialized>, options?: StreamOutOptions): Promise<Source<In>>;
 /**
- * Streams in parsed messages while retaining only the transport-frame size.
- * The size bounds downstream batching without keeping or copying the JSON.
+ * {@link streamInternal} that retains only the transport-frame size of each
+ * inbound message. The size bounds downstream batching without keeping or
+ * copying the JSON.
  */
-export declare function streamInWithSize<T extends JSONValue>(lc: LogContext, source: WebSocket, schema: v.Type<T>): Promise<Source<Sized<T>>>;
+export declare function streamInternalWithSize<In extends JSONValue, Out extends JSONValue = JSONValue>(lc: LogContext, ws: WebSocket, inSchema: v.Type<In>, outSource?: Source<Out>, options?: StreamOutOptions): Promise<Source<Sized<In>>>;
 export {};
 //# sourceMappingURL=streams.d.ts.map

package/out/zero-cache/src/types/streams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/streams.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"streams.d.ts","sourceRoot":"","sources":["../../../../../zero-cache/src/types/streams.ts"],"names":[],"mappings":"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"}