feat(watcher): add addField() for dynamic field registration after start (#101)

ConfigWatcher.field() was one-shot: calling it after start() threw.
addField() fills that gap — it works both before and after start().
When called post-start it fetches a targeted GetConfig snapshot to
seed the new field's initial value, cancels the current Subscribe
stream, and re-opens it with the full updated field list.

Internally, loadSnapshot() is refactored into a private
loadSnapshotForFields(paths) helper so both the full reconnect
path and the targeted addField path share the same logic.

Closes #70

Co-authored-by: Claude <noreply@anthropic.com>

Author: zeevdr

src/watcher.ts

@@ -384,11 +384,9 @@ export class ConfigWatcher extends EventEmitter {
 	}
 
 	/**
-	 * Register a field to watch.
+	 * Register a field to watch before `start()`.
 	 *
-	 * Must be called before `start()`. Returns a WatchedField that will be
-	 * populated with the initial value from the snapshot and updated in
-	 * real-time from the Subscribe stream.
+	 * Must be called before `start()`. For post-start registration use `addField()`.
 	 *
 	 * @param path - Dot-separated field path (e.g. "payments.fee").
 	 * @param converter - Type converter: String, Number, or Boolean.
@@ -403,13 +401,59 @@ export class ConfigWatcher extends EventEmitter {
 	 */
 	field<T>(path: string, converter: Converter, options: FieldOptions<T>): WatchedField<T> {
 		if (this.started) {
-			throw new DecreeError("cannot register fields after start()");
+			throw new DecreeError("cannot register fields after start(); use addField() instead");
 		}
 		const wf = new WatchedField<T>(path, converter, options);
 		this.fields.set(path, wf as WatchedField<unknown>);
 		return wf;
 	}
 
+	/**
+	 * Register a field to watch dynamically — works both before and after `start()`.
+	 *
+	 * When called after `start()`, loads the field's initial value from a GetConfig
+	 * snapshot and re-opens the Subscribe stream with the updated field list.
+	 *
+	 * @param path - Dot-separated field path (e.g. "payments.fee").
+	 * @param converter - Type converter: String, Number, or Boolean.
+	 * @param options - Options including the default value.
+	 * @returns A WatchedField instance for this path.
+	 * @throws DecreeError if called after stop().
+	 *
+	 * @example
+	 * ```ts
+	 * await watcher.start();
+	 * const label = await watcher.addField('payments.label', String, { default: '' });
+	 * console.log(label.value);
+	 * ```
+	 */
+	async addField<T>(
+		path: string,
+		converter: Converter,
+		options: FieldOptions<T>,
+	): Promise<WatchedField<T>> {
+		if (this.stopped) {
+			throw new DecreeError("cannot add fields after stop()");
+		}
+		const wf = new WatchedField<T>(path, converter, options);
+		this.fields.set(path, wf as WatchedField<unknown>);
+
+		if (this.started) {
+			await this.loadSnapshotForFields([path]);
+			if (this.reconnectTimer !== null) {
+				clearTimeout(this.reconnectTimer);
+				this.reconnectTimer = null;
+			}
+			if (this.stream) {
+				this.stream.cancel();
+				this.stream = null;
+			}
+			this.subscribe();
+		}
+
+		return wf;
+	}
+
 	/**
 	 * Load the initial snapshot and start the Subscribe stream.
 	 *
@@ -480,6 +524,10 @@ export class ConfigWatcher extends EventEmitter {
 	}
 
 	private async loadSnapshot(): Promise<void> {
+		await this.loadSnapshotForFields([...this.fields.keys()]);
+	}
+
+	private async loadSnapshotForFields(paths: string[]): Promise<void> {
 		const resp = await this.callGetConfig({
 			tenantId: this.tenantId,
 			includeDescriptions: false,
@@ -492,9 +540,11 @@ export class ConfigWatcher extends EventEmitter {
 			}
 		}
 
-		for (const [path, field] of this.fields) {
-			const raw = valueMap.get(path);
-			field._loadInitial(raw ?? null);
+		for (const path of paths) {
+			const field = this.fields.get(path);
+			if (field) {
+				field._loadInitial(valueMap.get(path) ?? null);
+			}
 		}
 	}
 

test/watcher.test.ts

@@ -416,13 +416,138 @@ describe("ConfigWatcher", () => {
 			await watcher.start();
 
 			expect(() => watcher.field("other.field", String, { default: "" })).toThrow(
-				"cannot register fields after start()",
+				"cannot register fields after start(); use addField() instead",
 			);
 
 			await watcher.stop();
 		});
 	});
 
+	describe("addField()", () => {
+		it("works before start — returns WatchedField at default value", async () => {
+			const watcher = createWatcher();
+			const field = await watcher.addField("payments.fee", Number, { default: 0.01 });
+			expect(field).toBeInstanceOf(WatchedField);
+			expect(field.value).toBe(0.01);
+		});
+
+		it("before start — field is included when start() runs", async () => {
+			const watcher = createWatcher();
+			const fee = await watcher.addField("payments.fee", Number, { default: 0.01 });
+
+			mockGetConfigSuccess([{ fieldPath: "payments.fee", value: { numberValue: 0.99 } }]);
+			await watcher.start();
+
+			expect(fee.value).toBe(0.99);
+			await watcher.stop();
+		});
+
+		it("after start — loads initial value and re-subscribes", async () => {
+			const watcher = createWatcher();
+			watcher.field("payments.fee", Number, { default: 0.01 });
+			mockGetConfigSuccess([{ fieldPath: "payments.fee", value: { numberValue: 0.05 } }]);
+			await watcher.start();
+
+			// New mock stream for the re-subscribe triggered by addField.
+			const newStream = createMockStream();
+			configStub.subscribe.mockReturnValue(newStream);
+			configStub.getConfig.mockImplementationOnce(
+				(_req: unknown, _meta: unknown, _opts: unknown, cb: (...args: unknown[]) => void) => {
+					cb(null, {
+						config: {
+							tenantId: "tenant-1",
+							version: 2,
+							values: [
+								{ fieldPath: "payments.label", value: { stringValue: "hello" }, checksum: "x" },
+							],
+						},
+					});
+				},
+			);
+
+			const label = await watcher.addField("payments.label", String, { default: "" });
+
+			expect(label.value).toBe("hello");
+			// Original stream cancelled, new one opened.
+			expect(mockStream.cancel).toHaveBeenCalledOnce();
+			expect(configStub.subscribe).toHaveBeenCalledTimes(2);
+
+			newStream.cancel = vi.fn();
+			await watcher.stop();
+		});
+
+		it("after start — new subscribe call includes added field path", async () => {
+			const watcher = createWatcher();
+			watcher.field("payments.fee", Number, { default: 0.01 });
+			mockGetConfigSuccess([]);
+			await watcher.start();
+
+			const newStream = createMockStream();
+			configStub.subscribe.mockReturnValue(newStream);
+			configStub.getConfig.mockImplementationOnce(
+				(_req: unknown, _meta: unknown, _opts: unknown, cb: (...args: unknown[]) => void) => {
+					cb(null, { config: { tenantId: "tenant-1", version: 2, values: [] } });
+				},
+			);
+
+			await watcher.addField("payments.label", String, { default: "" });
+
+			const subscribeArgs = configStub.subscribe.mock.calls[1];
+			expect(subscribeArgs?.[0]).toMatchObject({
+				tenantId: "tenant-1",
+				fieldPaths: expect.arrayContaining(["payments.fee", "payments.label"]),
+			});
+
+			newStream.cancel = vi.fn();
+			await watcher.stop();
+		});
+
+		it("after start — added field receives live changes", async () => {
+			const watcher = createWatcher();
+			watcher.field("payments.fee", Number, { default: 0.01 });
+			mockGetConfigSuccess([]);
+			await watcher.start();
+
+			const newStream = createMockStream();
+			configStub.subscribe.mockReturnValue(newStream);
+			configStub.getConfig.mockImplementationOnce(
+				(_req: unknown, _meta: unknown, _opts: unknown, cb: (...args: unknown[]) => void) => {
+					cb(null, { config: { tenantId: "tenant-1", version: 2, values: [] } });
+				},
+			);
+
+			const label = await watcher.addField("payments.label", String, { default: "" });
+
+			newStream.emit("data", {
+				change: {
+					tenantId: "tenant-1",
+					version: 3,
+					fieldPath: "payments.label",
+					oldValue: { stringValue: "" },
+					newValue: { stringValue: "updated" },
+					changedBy: "admin",
+					changedAt: new Date(),
+				},
+			});
+
+			expect(label.value).toBe("updated");
+
+			newStream.cancel = vi.fn();
+			await watcher.stop();
+		});
+
+		it("throws after stop()", async () => {
+			const watcher = createWatcher();
+			mockGetConfigSuccess([]);
+			await watcher.start();
+			await watcher.stop();
+
+			await expect(watcher.addField("payments.fee", Number, { default: 0.01 })).rejects.toThrow(
+				"cannot add fields after stop()",
+			);
+		});
+	});
+
 	describe("start()", () => {
 		it("loads initial snapshot into registered fields", async () => {
 			const watcher = createWatcher();