feat: support merge in vars

Author: ping-maxwell

packages/experimental/src/fn.ts

@@ -7,6 +7,7 @@ import {
 } from "./error";
 import {
 	type ApplyOns,
+	collectMergeSeeds,
 	collectUsable,
 	type InputVarExtra,
 	type InputVarExtraOut,
@@ -43,9 +44,11 @@ import {
 	type Cells,
 	contextScope,
 	type Frame,
+	getCell,
 	readVar,
 	readVarThrough,
 	type VarDefination,
+	viewMergeVar,
 	writeVar,
 } from "./var";
 
@@ -664,6 +667,7 @@ const defineFn = (
 	for (const mod of modules) scanMembers(mod);
 
 	const usable = collectUsable(modules);
+	const mergeSeeds = collectMergeSeeds(modules);
 
 	// A tuple input means POSITIONAL args: the callable takes one arg per
 	// declared position, then the parent context.
@@ -726,6 +730,15 @@ const defineFn = (
 			: callArgs[0];
 		const parent: any = tupleInput ? callArgs[tupleInput.length] : callArgs[1];
 		const cells: Cells = parent?.[STORE] ?? {};
+		// Root scope: fold merge-var contributions from `use` into cells
+		// before anything reads them (storage default + helper namespaces).
+		if (!parent?.[STORE]) {
+			for (const [name, value] of Object.entries(mergeSeeds)) {
+				const cell = getCell(cells, name);
+				cell.value = value;
+				cell.accumulate = true;
+			}
+		}
 		// The lock travels the whole subtree: once any frame above is
 		// readonly, every write below throws - handlers, nested fns,
 		// interceptors, input-var seeding, all of it.
@@ -886,7 +899,8 @@ const defineFn = (
 				if (isVar(used)) {
 					const varName = (used as { name: string }).name;
 					Object.defineProperty(target, name, {
-						get: () => readVarThrough(frame, varName),
+						get: () =>
+							viewMergeVar(varName, readVarThrough(frame, varName), ctx),
 						set: (value: unknown) => writeVar(frame, varName, value),
 						enumerable: true,
 						configurable: true,

packages/experimental/src/index.ts

@@ -16,9 +16,12 @@ interface V {
 	fn: Fn;
 	var: <N extends LiteralString, S = undefined, D = undefined>(
 		name: N,
-		options?: { default?: D; schema?: S },
+		options?: { default?: D; schema?: S; merge?: boolean },
 		// A default the schema already covers (e.g. `{}` against an
 		// all-optional shape) is absorbed; `default: null` still unions in.
+		// `merge: true` - object contributions from `use` modules (same-name
+		// defaults, same-key namespaces) shallow-merge onto the value;
+		// writes accumulate the same way.
 	) => VarDefination<
 		N,
 		[S] extends [undefined]

packages/experimental/src/module.ts

@@ -265,6 +265,10 @@ export const isNamespace = (
  * name (`{ cookie: { options: cookieOptions } }` -> `c.cookie.options`
  * reads/writes the var). Storage mounts whole (`c.db.user.findOne`).
  * Groups holding nothing (however deep) drop out.
+ *
+ * A `merge: true` var keeps its slot when a later module exports a
+ * namespace under the same key - those helpers are folded into the var
+ * value by {@link collectMergeSeeds}, not bound as a rival namespace.
  */
 export const collectUsable = (
 	modules: readonly Module[],
@@ -274,6 +278,14 @@ export const collectUsable = (
 		value !== null &&
 		"$models" in value &&
 		typeof (value as { $adapter?: unknown }).$adapter === "function";
+	const isMergeVar = (value: unknown) =>
+		isVar(value) && (value as { $merge?: boolean }).$merge === true;
+	const isGroup = (value: unknown) =>
+		value !== null &&
+		typeof value === "object" &&
+		!isFn(value) &&
+		!isVar(value) &&
+		!isStorageValue(value);
 	const walk = (mod: Record<string, unknown>): Record<string, unknown> => {
 		const out: Record<string, unknown> = {};
 		for (const [name, value] of Object.entries(mod)) {
@@ -286,11 +298,105 @@ export const collectUsable = (
 		}
 		return out;
 	};
+	const assign = (
+		target: Record<string, unknown>,
+		name: string,
+		value: unknown,
+	) => {
+		const existing = target[name];
+		if (isMergeVar(existing) && isGroup(value)) return;
+		if (isMergeVar(value) && isGroup(existing)) {
+			target[name] = value;
+			return;
+		}
+		if (isGroup(existing) && isGroup(value)) {
+			const group = { ...(existing as Record<string, unknown>) };
+			for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+				assign(group, k, v);
+			}
+			target[name] = group;
+			return;
+		}
+		target[name] = value;
+	};
 	const fns: Record<string, unknown> = {};
-	for (const mod of resolveModules(modules)) Object.assign(fns, walk(mod));
+	for (const mod of resolveModules(modules)) {
+		for (const [name, value] of Object.entries(walk(mod))) {
+			assign(fns, name, value);
+		}
+	}
 	return fns;
 };
 
+/**
+ * Initial values for `merge: true` vars: walk `use` modules in order and
+ * shallow-merge (1) each merge-var's `default` and (2) namespaces exported
+ * under the same key as a merge var. Later leaf keys win.
+ */
+export const collectMergeSeeds = (
+	modules: readonly Module[],
+): Record<string, unknown> => {
+	const resolved = resolveModules(modules);
+	const seeds: Record<string, unknown> = {};
+	const keyToVar = new Map<string, string>();
+
+	const isMergeVar = (
+		value: unknown,
+	): value is VarDefination<string, unknown> & {
+		$merge: true;
+		default?: unknown;
+		name: string;
+	} => isVar(value) && (value as { $merge?: boolean }).$merge === true;
+
+	const mergeInto = (name: string, contribution: unknown) => {
+		if (contribution === undefined) return;
+		const current = seeds[name];
+		if (
+			contribution !== null &&
+			typeof contribution === "object" &&
+			!Array.isArray(contribution) &&
+			current !== null &&
+			typeof current === "object" &&
+			!Array.isArray(current)
+		) {
+			seeds[name] = {
+				...(current as Record<string, unknown>),
+				...(contribution as Record<string, unknown>),
+			};
+		} else {
+			seeds[name] = contribution;
+		}
+	};
+
+	const index = (mod: Record<string, unknown>) => {
+		for (const [key, value] of Object.entries(mod)) {
+			if (isMergeVar(value)) {
+				keyToVar.set(key, value.name);
+			} else if (isNamespace(value)) {
+				index(value);
+			}
+		}
+	};
+	for (const mod of resolved) index(mod);
+
+	const contribute = (mod: Record<string, unknown>) => {
+		for (const [key, value] of Object.entries(mod)) {
+			if (isMergeVar(value)) {
+				mergeInto(value.name, value.default);
+				continue;
+			}
+			if (isNamespace(value)) {
+				const varName = keyToVar.get(key);
+				if (varName) mergeInto(varName, value);
+				else contribute(value);
+			}
+		}
+	};
+	for (const mod of resolved) contribute(mod);
+
+	return seeds;
+};
+
 export const isOn = (value: any): value is OnEntry<string> =>
 	value?.$on === true;
 

packages/experimental/src/var.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, expectTypeOf, it } from "vitest";
-import { v } from "./index";
+import { memoryAdapter, v } from "./index";
 
 describe("vars", () => {
 	const note = v.var("vt_note", { default: "" });
@@ -124,3 +124,49 @@ describe("record vars", () => {
 		await expect(entry()).resolves.toEqual({ title: "hi", body: "there" });
 	});
 });
+
+describe("merge vars", () => {
+	it("use modules merge helpers onto a storage default under the same key", async () => {
+		const row = v.var("vt_merge_row", {
+			default: null,
+			schema: v.object({ id: v.string(), tag: v.string() }),
+		});
+		const store = v.storage(memoryAdapter(), { row });
+		const db = v.var("vt_merge_db", {
+			merge: true,
+			default: store,
+		});
+		const byTag = v.fn(
+			"vt.merge.byTag",
+			{
+				input: { tag: v.string() },
+				use: [{ db, row }],
+			},
+			async (c) => c.vt_merge_db.row.findMany({ tag: c.input.tag }),
+		);
+		const core = { db, row };
+		const plugin = { db: { byTag } };
+		const entry = v.fn({ use: [core, plugin] }, async (c) => {
+			await c.vt_merge_db.row.create({ id: "1", tag: "a" });
+			await c.vt_merge_db.row.create({ id: "2", tag: "b" });
+			return c.vt_merge_db.byTag({ tag: "a" });
+		});
+		await expect(entry()).resolves.toEqual([{ id: "1", tag: "a" }]);
+	});
+
+	it("later use module wins on a conflicting helper key", async () => {
+		const base = v.var("vt_merge_obj", {
+			merge: true,
+			default: { n: 0, from: "base" },
+		});
+		const first = v.fn("vt.merge.first", () => "first");
+		const second = v.fn("vt.merge.second", () => "second");
+		const entry = v.fn(
+			{
+				use: [{ obj: base }, { obj: { who: first } }, { obj: { who: second } }],
+			},
+			(c) => c.vt_merge_obj.who(),
+		);
+		expect(entry()).toBe("second");
+	});
+});

packages/experimental/src/var.ts

@@ -31,6 +31,12 @@ export interface VarDefination<
 	$source?: Source;
 	/** Whole-var plugin attributes (field attrs live on the schema). */
 	$attrs?: AttrBag;
+	/**
+	 * Object contributions from `use` modules merge instead of replacing:
+	 * same-name var defaults and same-export-key namespaces shallow-merge
+	 * onto this value (storage default + helpers). Writes accumulate too.
+	 */
+	$merge?: boolean;
 	customize: <S>(options: {
 		schema: (v: VarCustomizer<T>) => S;
 	}) => VarDefination<N, InferInput<S>, S>;
@@ -74,6 +80,7 @@ export const makeVar = (name: string, options: any = {}): any => {
 		schema,
 		...(options.attrs !== undefined ? { $attrs: options.attrs } : {}),
 		$accessor: options.accessor === true,
+		$merge: options.merge === true,
 		$derive: options.derive,
 		customize: (opts: any) =>
 			makeVar(name, {
@@ -117,7 +124,7 @@ export type Cell = {
 	derive?: { source: string; get: (value: any) => any };
 	/** A direct write to a derived var shadows its computation. */
 	shadowed: boolean;
-	/** Record var: `set()` merges instead of replacing. */
+	/** Record / merge var: `set()` merges instead of replacing. */
 	accumulate: boolean;
 };
 
@@ -132,7 +139,7 @@ export const getCell = (cells: Cells, name: string): Cell => {
 		value: def?.$derive ? undefined : def?.$accessor ? {} : def?.default,
 		derive: def?.$derive,
 		shadowed: false,
-		accumulate: def?.$accessor === true,
+		accumulate: def?.$accessor === true || def?.$merge === true,
 	};
 	cells[name] = cell;
 	return cell;
@@ -274,6 +281,38 @@ export const readVarThrough = (frame: Frame, name: string): unknown => {
 
 /* ---------------------------------- scope ---------------------------------- */
 
+/**
+ * Merge-var reads expose a shallow view that binds any `$fn` member into
+ * this context - helpers contributed via `use` call like usable fns.
+ */
+export const viewMergeVar = (
+	name: string,
+	value: unknown,
+	ctx: unknown,
+): unknown => {
+	const def = varRegistry.get(name);
+	if (!def?.$merge || value == null || typeof value !== "object") return value;
+	return new Proxy(value as object, {
+		get: (t, prop, receiver) => {
+			const member = Reflect.get(t, prop, receiver);
+			if (
+				typeof member !== "function" ||
+				(member as { $fn?: boolean }).$fn !== true
+			) {
+				return member;
+			}
+			const usedArity = (member as { $arity?: number }).$arity;
+			return usedArity === undefined
+				? (i?: unknown) => (member as any)(i, ctx)
+				: (...args: unknown[]) => {
+						const padded = args.slice(0, usedArity);
+						while (padded.length < usedArity) padded.push(undefined);
+						return (member as any)(...padded, ctx);
+					};
+		},
+	});
+};
+
 /**
  * The fn context for one frame: `base` carries the fixed surface (input,
  * error, fn, types, the bound `use` fns, internal symbols) and EVERY
@@ -285,12 +324,13 @@ export const readVarThrough = (frame: Frame, name: string): unknown => {
  */
 export const contextScope = (frame: Frame, base: object): any =>
 	new Proxy(base, {
-		get: (t, prop, receiver) =>
-			prop in t
-				? Reflect.get(t, prop, receiver)
-				: typeof prop === "string"
-					? readVarThrough(frame, prop)
-					: undefined,
+		get: (t, prop, receiver) => {
+			if (prop in t) return Reflect.get(t, prop, receiver);
+			if (typeof prop === "string") {
+				return viewMergeVar(prop, readVarThrough(frame, prop), receiver);
+			}
+			return undefined;
+		},
 		set: (t, prop, value, receiver) => {
 			if (typeof prop !== "string" || prop in t) {
 				return Reflect.set(t, prop, value, receiver);