@sylphx/lens-server 2.7.2 → 2.8.1

package/dist/index.d.ts

@@ -512,7 +512,7 @@ interface LensServerConfig<
 	plugins?: ServerPlugin[] | undefined;
 }
 /** Field mode for entity fields */
-type FieldMode = "exposed" | "resolve" | "subscribe";
+type FieldMode = "exposed" | "resolve" | "subscribe" | "live";
 /** Entity field metadata for client-side routing decisions */
 interface EntityFieldMetadata {
 	[fieldName: string]: FieldMode;

package/dist/index.js

@@ -575,6 +575,7 @@ class LensServerImpl {
                 emitProcessing = true;
                 let command = emitQueue.dequeue();
                 while (command !== null && !cancelled) {
+                  this.clearLoaders();
                   currentState = this.applyEmitCommand(command, currentState);
                   const fieldEmitFactory = isQuery ? this.createFieldEmitFactory(() => currentState, (state) => {
                     currentState = state;
@@ -707,11 +708,16 @@ class LensServerImpl {
     return (fieldPath) => {
       if (!fieldPath)
         return;
-      return (newValue) => {
-        const state = getCurrentState();
-        if (!state || typeof state !== "object")
+      const state = getCurrentState();
+      const currentFieldValue = state ? this.getFieldByPath(state, fieldPath) : undefined;
+      const isArray = Array.isArray(currentFieldValue);
+      const emitHandler = (command) => {
+        const fullState = getCurrentState();
+        if (!fullState || typeof fullState !== "object")
           return;
-        const updatedState = this.setFieldByPath(state, fieldPath, newValue);
+        const fieldValue = this.getFieldByPath(fullState, fieldPath);
+        const newFieldValue = this.applyEmitCommand(command, fieldValue);
+        const updatedState = this.setFieldByPath(fullState, fieldPath, newFieldValue);
         setCurrentState(updatedState);
         (async () => {
           try {
@@ -724,8 +730,21 @@ class LensServerImpl {
           }
         })();
       };
+      return createEmit(emitHandler, isArray);
     };
   }
+  getFieldByPath(obj, path) {
+    if (!obj || typeof obj !== "object")
+      return;
+    const parts = path.split(".");
+    let current = obj;
+    for (const part of parts) {
+      if (!current || typeof current !== "object")
+        return;
+      current = current[part];
+    }
+    return current;
+  }
   setFieldByPath(obj, path, value) {
     const parts = path.split(".");
     if (parts.length === 1) {
@@ -779,26 +798,68 @@ class LensServerImpl {
         result[field] = await this.resolveEntityFields(existingValue, nestedInputs, context, currentPath, onCleanup, createFieldEmit);
         continue;
       }
-      if (hasArgs || context) {
+      const fieldMode = resolverDef.getFieldMode(field);
+      if (fieldMode === "live") {
         try {
-          const extendedCtx = {
-            ...context ?? {},
-            emit: createFieldEmit(currentPath),
-            onCleanup
-          };
-          if (resolverDef.isSubscription(field)) {
-            result[field] = null;
-            resolverDef.resolveField(field, obj, args, extendedCtx).catch(() => {});
+          if (hasArgs) {
+            result[field] = await resolverDef.resolveField(field, obj, args, context ?? {});
           } else {
-            result[field] = await resolverDef.resolveField(field, obj, args, extendedCtx);
+            const loaderKey = `${typeName}.${field}`;
+            const loader = this.getOrCreateLoaderForField(loaderKey, resolverDef, field, context ?? {});
+            result[field] = await loader.load(obj);
+          }
+          const publisher = resolverDef.subscribeField(field, obj, args, context ?? {});
+          if (publisher && createFieldEmit && onCleanup) {
+            try {
+              const fieldEmit = createFieldEmit(currentPath);
+              if (fieldEmit) {
+                publisher({
+                  emit: fieldEmit,
+                  onCleanup: (fn) => {
+                    onCleanup(fn);
+                    return fn;
+                  }
+                });
+              }
+            } catch {}
+          }
+        } catch {
+          result[field] = null;
+        }
+      } else if (fieldMode === "subscribe") {
+        try {
+          result[field] = null;
+          if (createFieldEmit && onCleanup) {
+            try {
+              const fieldEmit = createFieldEmit(currentPath);
+              if (fieldEmit) {
+                const legacyCtx = {
+                  ...context ?? {},
+                  emit: fieldEmit,
+                  onCleanup: (fn) => {
+                    onCleanup(fn);
+                    return fn;
+                  }
+                };
+                resolverDef.subscribeFieldLegacy(field, obj, args, legacyCtx);
+              }
+            } catch {}
           }
         } catch {
           result[field] = null;
         }
       } else {
-        const loaderKey = `${typeName}.${field}`;
-        const loader = this.getOrCreateLoaderForField(loaderKey, resolverDef, field);
-        result[field] = await loader.load(obj);
+        try {
+          if (hasArgs) {
+            result[field] = await resolverDef.resolveField(field, obj, args, context ?? {});
+          } else {
+            const loaderKey = `${typeName}.${field}`;
+            const loader = this.getOrCreateLoaderForField(loaderKey, resolverDef, field, context ?? {});
+            result[field] = await loader.load(obj);
+          }
+        } catch {
+          result[field] = null;
+        }
       }
       result[field] = await this.resolveEntityFields(result[field], nestedInputs, context, currentPath, onCleanup, createFieldEmit);
     }
@@ -827,11 +888,10 @@ class LensServerImpl {
     const matchingFields = fieldNames.filter((field) => (field in obj));
     return matchingFields.length / fieldNames.length;
   }
-  getOrCreateLoaderForField(loaderKey, resolverDef, fieldName) {
+  getOrCreateLoaderForField(loaderKey, resolverDef, fieldName, context) {
     let loader = this.loaders.get(loaderKey);
     if (!loader) {
       loader = new DataLoader(async (parents) => {
-        const context = tryUseContext() ?? {};
         const results = [];
         for (const parent of parents) {
           try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-server",
-	"version": "2.7.2",
+	"version": "2.8.1",
 	"description": "Server runtime for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -30,7 +30,7 @@
 	"author": "SylphxAI",
 	"license": "MIT",
 	"dependencies": {
-		"@sylphx/lens-core": "^2.5.0"
+		"@sylphx/lens-core": "^2.6.1"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",

package/src/server/create.test.ts

@@ -856,22 +856,27 @@ describe("field resolvers", () => {
 			posts: [{ id: "p1", title: "Post 1", authorId: "a1" }],
 		};
 
+		// Use .resolve().subscribe() to get onCleanup access
+		// Per ADR-002: .resolve() alone is pure/batchable, no emit/onCleanup
+		// .resolve().subscribe() gives initial value + subscription capabilities
 		const authorResolver = resolver<{ db: typeof mockDb }>()(Author, (f) => ({
 			id: f.expose("id"),
 			name: f.expose("name"),
-			posts: f.many(Post).resolve(({ parent, ctx }) => {
-				// Track if onCleanup was received (via ctx)
-				resolverReceivedOnCleanup = ctx.onCleanup !== undefined;
-
-				// Register a cleanup if available
-				if (ctx.onCleanup) {
-					ctx.onCleanup(() => {
+			posts: f
+				.many(Post)
+				.resolve(({ parent, ctx }) => {
+					// Initial resolution (batchable, no emit/onCleanup)
+					return ctx.db.posts.filter((p) => p.authorId === parent.id);
+				})
+				.subscribe(() => ({ onCleanup }) => {
+					// Publisher pattern: emit/onCleanup come from callback, not ctx
+					resolverReceivedOnCleanup = true;
+
+					// Register cleanup
+					onCleanup(() => {
 						cleanupCalled = true;
 					});
-				}
-
-				return ctx.db.posts.filter((p) => p.authorId === parent.id);
-			}),
+				}),
 		}));
 
 		const getAuthor = query<{ db: typeof mockDb }>()
@@ -940,23 +945,27 @@ describe("field resolvers", () => {
 		// Track field emit
 		let capturedFieldEmit: ((value: unknown) => void) | undefined;
 
+		// Use .resolve().subscribe() to get emit access
+		// Per ADR-002: .resolve() alone is pure/batchable, no emit/onCleanup
+		// .resolve().subscribe() gives initial value + subscription capabilities
 		const authorResolver = resolver<{ db: typeof mockDb }>()(Author, (f) => ({
 			id: f.expose("id"),
 			name: f.expose("name"),
-			posts: f.many(Post).resolve(({ parent, ctx }) => {
-				// Capture the field emit for later use
-				capturedFieldEmit = ctx.emit;
-
-				// Set up a mock subscription that will use field emit
-				if (ctx.emit && ctx.onCleanup) {
-					// Simulate subscription setup
-					ctx.onCleanup(() => {
+			posts: f
+				.many(Post)
+				.resolve(({ parent, ctx }) => {
+					// Initial resolution (batchable, no emit)
+					return ctx.db.posts.filter((p) => p.authorId === parent.id);
+				})
+				.subscribe(() => ({ emit, onCleanup }) => {
+					// Publisher pattern: emit/onCleanup come from callback
+					capturedFieldEmit = emit;
+
+					// Register cleanup
+					onCleanup(() => {
 						capturedFieldEmit = undefined;
 					});
-				}
-
-				return ctx.db.posts.filter((p) => p.authorId === parent.id);
-			}),
+				}),
 		}));
 
 		const getAuthor = query<{ db: typeof mockDb }>()
@@ -1077,6 +1086,123 @@ describe("field resolvers", () => {
 
 		subscription.unsubscribe();
 	});
+
+	it(".resolve().subscribe() pattern enables batching with live updates", async () => {
+		// ADR-002: Two-Phase Field Resolution
+		// .resolve() handles initial data (batchable)
+		// .subscribe() handles live updates (fire-and-forget)
+
+		const Author = entity("Author", {
+			id: t.id(),
+			name: t.string(),
+		});
+
+		const Post = entity("Post", {
+			id: t.id(),
+			title: t.string(),
+			authorId: t.string(),
+		});
+
+		const mockDb = {
+			authors: [{ id: "a1", name: "Alice" }],
+			posts: [
+				{ id: "p1", title: "Post 1", authorId: "a1" },
+				{ id: "p2", title: "Post 2", authorId: "a1" },
+			],
+		};
+
+		// Track calls and captured emit
+		let resolveCallCount = 0;
+		let subscribeCallCount = 0;
+		let capturedFieldEmit: ((value: unknown) => void) | undefined;
+
+		// Use .resolve().subscribe() pattern
+		const authorResolver = resolver<{ db: typeof mockDb }>()(Author, (f) => ({
+			id: f.expose("id"),
+			name: f.expose("name"),
+			posts: f
+				.many(Post)
+				.resolve(({ parent, ctx }) => {
+					// Phase 1: Initial resolution (batchable, no emit/onCleanup)
+					resolveCallCount++;
+					return ctx.db.posts.filter((p) => p.authorId === parent.id);
+				})
+				.subscribe(() => ({ emit, onCleanup }) => {
+					// Phase 2: Publisher pattern - emit/onCleanup from callback
+					subscribeCallCount++;
+					capturedFieldEmit = emit;
+
+					onCleanup(() => {
+						capturedFieldEmit = undefined;
+					});
+				}),
+		}));
+
+		const getAuthor = query<{ db: typeof mockDb }>()
+			.input(z.object({ id: z.string() }))
+			.returns(Author)
+			.resolve(({ input, ctx }) => {
+				const author = ctx.db.authors.find((a) => a.id === input.id);
+				if (!author) throw new Error("Author not found");
+				return author;
+			});
+
+		const server = createApp({
+			entities: { Author, Post },
+			queries: { getAuthor },
+			resolvers: [authorResolver],
+			context: () => ({ db: mockDb }),
+		});
+
+		const results: unknown[] = [];
+		const subscription = server
+			.execute({
+				path: "getAuthor",
+				input: {
+					id: "a1",
+					$select: {
+						id: true,
+						name: true,
+						posts: { select: { id: true, title: true } },
+					},
+				},
+			})
+			.subscribe({
+				next: (result) => {
+					results.push(result);
+				},
+			});
+
+		// Wait for initial result
+		await new Promise((resolve) => setTimeout(resolve, 50));
+
+		// Verify initial resolution
+		expect(results.length).toBe(1);
+		expect(resolveCallCount).toBe(1); // Resolver called once
+		expect(subscribeCallCount).toBe(1); // Subscriber called once
+		expect(capturedFieldEmit).toBeDefined(); // Emit captured from subscribe phase
+
+		const initialResult = results[0] as { data: { posts: { id: string }[] } };
+		expect(initialResult.data.posts).toHaveLength(2);
+
+		// Use field emit to push update (from subscribe phase)
+		const updatedPosts = [
+			{ id: "p1", title: "Updated 1", authorId: "a1" },
+			{ id: "p2", title: "Updated 2", authorId: "a1" },
+			{ id: "p3", title: "New Post", authorId: "a1" },
+		];
+		capturedFieldEmit!(updatedPosts);
+
+		// Wait for update
+		await new Promise((resolve) => setTimeout(resolve, 50));
+
+		expect(results.length).toBe(2);
+		const updatedResult = results[1] as { data: { posts: { id: string; title: string }[] } };
+		expect(updatedResult.data.posts).toHaveLength(3);
+		expect(updatedResult.data.posts[2].title).toBe("New Post");
+
+		subscription.unsubscribe();
+	});
 });
 
 // =============================================================================

package/src/server/create.ts

@@ -19,6 +19,7 @@ import {
 	type ContextValue,
 	createEmit,
 	createResolverFromEntity,
+	type Emit,
 	type EmitCommand,
 	type EntityDef,
 	flattenRouter,
@@ -33,7 +34,7 @@ import {
 	type RouterDef,
 	valuesEqual,
 } from "@sylphx/lens-core";
-import { createContext, runWithContext, tryUseContext } from "../context/index.js";
+import { createContext, runWithContext } from "../context/index.js";
 import {
 	createPluginManager,
 	type PluginManager,
@@ -552,6 +553,10 @@ class LensServerImpl<
 
 								let command = emitQueue.dequeue();
 								while (command !== null && !cancelled) {
+									// Clear DataLoader cache before re-processing
+									// This ensures field resolvers re-run with fresh data
+									this.clearLoaders();
+
 									currentState = this.applyEmitCommand(command, currentState);
 
 									// Process through field resolvers (unlike before where we bypassed this)
@@ -760,7 +765,7 @@ class LensServerImpl<
 
 	/**
 	 * Factory type for creating field-level emit handlers.
-	 * Each field gets its own emit that updates just that field path.
+	 * Each field gets its own emit with full Emit<T> API (.delta, .patch, .push, etc).
 	 */
 	private createFieldEmitFactory(
 		getCurrentState: () => unknown,
@@ -769,19 +774,29 @@ class LensServerImpl<
 		select: SelectionObject | undefined,
 		context: TContext | undefined,
 		onCleanup: ((fn: () => void) => void) | undefined,
-	): (fieldPath: string) => ((value: unknown) => void) | undefined {
+	): (fieldPath: string) => Emit<unknown> | undefined {
 		return (fieldPath: string) => {
 			if (!fieldPath) return undefined;
 
-			return (newValue: unknown) => {
-				// Get current state and update the field at the given path
-				const state = getCurrentState();
-				if (!state || typeof state !== "object") return;
+			// Determine if field value is an array (check current state)
+			const state = getCurrentState();
+			const currentFieldValue = state ? this.getFieldByPath(state, fieldPath) : undefined;
+			const isArray = Array.isArray(currentFieldValue);
+
+			// Create emit handler that applies commands to the field's value
+			const emitHandler = (command: EmitCommand) => {
+				const fullState = getCurrentState();
+				if (!fullState || typeof fullState !== "object") return;
+
+				// Get current field value and apply command to it
+				const fieldValue = this.getFieldByPath(fullState, fieldPath);
+				const newFieldValue = this.applyEmitCommand(command, fieldValue);
 
+				// Update state with new field value
 				const updatedState = this.setFieldByPath(
-					state as Record<string, unknown>,
+					fullState as Record<string, unknown>,
 					fieldPath,
-					newValue,
+					newFieldValue,
 				);
 				setCurrentState(updatedState);
 
@@ -812,9 +827,25 @@ class LensServerImpl<
 					}
 				})();
 			};
+
+			return createEmit<unknown>(emitHandler, isArray);
 		};
 	}
 
+	/**
+	 * Get a value at a nested path in an object.
+	 */
+	private getFieldByPath(obj: unknown, path: string): unknown {
+		if (!obj || typeof obj !== "object") return undefined;
+		const parts = path.split(".");
+		let current: unknown = obj;
+		for (const part of parts) {
+			if (!current || typeof current !== "object") return undefined;
+			current = (current as Record<string, unknown>)[part];
+		}
+		return current;
+	}
+
 	/**
 	 * Set a value at a nested path in an object.
 	 * Creates a shallow copy at each level.
@@ -846,7 +877,7 @@ class LensServerImpl<
 		select?: SelectionObject,
 		context?: TContext,
 		onCleanup?: (fn: () => void) => void,
-		createFieldEmit?: (fieldPath: string) => ((value: unknown) => void) | undefined,
+		createFieldEmit?: (fieldPath: string) => Emit<unknown> | undefined,
 	): Promise<T> {
 		if (!data) return data;
 
@@ -884,7 +915,7 @@ class LensServerImpl<
 		context?: TContext,
 		fieldPath = "",
 		onCleanup?: (fn: () => void) => void,
-		createFieldEmit?: (fieldPath: string) => ((value: unknown) => void) | undefined,
+		createFieldEmit?: (fieldPath: string) => Emit<unknown> | undefined,
 	): Promise<T> {
 		if (!data || !this.resolverMap) return data;
 
@@ -941,40 +972,101 @@ class LensServerImpl<
 				continue;
 			}
 
-			// Resolve the field
-			if (hasArgs || context) {
-				// Direct resolution when we have args or context (skip DataLoader)
+			// Resolve the field based on mode
+			// ADR-002: Two-Phase Field Resolution
+			const fieldMode = resolverDef.getFieldMode(field);
+
+			if (fieldMode === "live") {
+				// LIVE MODE: Two-phase resolution
+				// Phase 1: Run resolver for initial value (batchable)
+				// Phase 2: Run subscriber for live updates (fire-and-forget)
 				try {
-					// Build extended context with emit and onCleanup
-					// Lens is a live query library - these are always available
-					const extendedCtx = {
-						...(context ?? {}),
-						emit: createFieldEmit!(currentPath),
-						onCleanup: onCleanup!,
-					};
+					// Phase 1: Get initial value (no emit/onCleanup needed)
+					if (hasArgs) {
+						// Direct resolution with args
+						result[field] = await resolverDef.resolveField(field, obj, args, context ?? {});
+					} else {
+						// Use DataLoader for batching
+						const loaderKey = `${typeName}.${field}`;
+						const loader = this.getOrCreateLoaderForField(
+							loaderKey,
+							resolverDef,
+							field,
+							context ?? ({} as TContext),
+						);
+						result[field] = await loader.load(obj);
+					}
 
-					// Check if field is a subscription (uses emit pattern)
-					if (resolverDef.isSubscription(field)) {
-						// Subscription fields use emit pattern - don't await completion
-						// The resolver runs in background, pushing values via emit()
-						// Set initial value to null, emit() will update it
-						result[field] = null;
-						// Start resolver without awaiting (fire and forget)
-						resolverDef.resolveField(field, obj, args, extendedCtx).catch(() => {
+					// Phase 2: Set up subscription (fire-and-forget)
+					// Publisher pattern: get publisher function and call with callbacks
+					const publisher = resolverDef.subscribeField(field, obj, args, context ?? {});
+					if (publisher && createFieldEmit && onCleanup) {
+						try {
+							const fieldEmit = createFieldEmit(currentPath);
+							if (fieldEmit) {
+								publisher({
+									emit: fieldEmit,
+									onCleanup: (fn) => {
+										onCleanup(fn);
+										return fn;
+									},
+								});
+							}
+						} catch {
 							// Subscription errors are handled via emit, ignore here
-						});
-					} else {
-						// Regular resolved field - await the result
-						result[field] = await resolverDef.resolveField(field, obj, args, extendedCtx);
+						}
+					}
+				} catch {
+					result[field] = null;
+				}
+			} else if (fieldMode === "subscribe") {
+				// SUBSCRIBE MODE (legacy): Call resolver with ctx.emit/ctx.onCleanup
+				// Legacy mode - resolver handles both initial value and updates via ctx.emit
+				try {
+					result[field] = null;
+					if (createFieldEmit && onCleanup) {
+						try {
+							const fieldEmit = createFieldEmit(currentPath);
+							if (fieldEmit) {
+								// Build legacy ctx with emit/onCleanup
+								const legacyCtx = {
+									...(context ?? {}),
+									emit: fieldEmit,
+									onCleanup: (fn: () => void) => {
+										onCleanup(fn);
+										return fn;
+									},
+								};
+								// Call legacy subscription method
+								resolverDef.subscribeFieldLegacy(field, obj, args, legacyCtx);
+							}
+						} catch {
+							// Subscription errors are handled via emit, ignore here
+						}
 					}
 				} catch {
 					result[field] = null;
 				}
 			} else {
-				// Use DataLoader for batching when no args (default case)
-				const loaderKey = `${typeName}.${field}`;
-				const loader = this.getOrCreateLoaderForField(loaderKey, resolverDef, field);
-				result[field] = await loader.load(obj);
+				// RESOLVE MODE: One-shot resolution (batchable)
+				try {
+					if (hasArgs) {
+						// Direct resolution with args (no batching)
+						result[field] = await resolverDef.resolveField(field, obj, args, context ?? {});
+					} else {
+						// Use DataLoader for batching
+						const loaderKey = `${typeName}.${field}`;
+						const loader = this.getOrCreateLoaderForField(
+							loaderKey,
+							resolverDef,
+							field,
+							context ?? ({} as TContext),
+						);
+						result[field] = await loader.load(obj);
+					}
+				} catch {
+					result[field] = null;
+				}
 			}
 
 			// Recursively resolve nested fields
@@ -1041,12 +1133,13 @@ class LensServerImpl<
 		loaderKey: string,
 		resolverDef: ResolverDef<any, any, any>,
 		fieldName: string,
+		context: TContext,
 	): DataLoader<unknown, unknown> {
 		let loader = this.loaders.get(loaderKey);
 		if (!loader) {
+			// Capture context at loader creation time
+			// This ensures the batch function has access to request context
 			loader = new DataLoader(async (parents: unknown[]) => {
-				// Get context from AsyncLocalStorage - maintains request context in batched calls
-				const context = tryUseContext<TContext>() ?? ({} as TContext);
 				const results: unknown[] = [];
 				for (const parent of parents) {
 					try {

package/src/server/types.ts

@@ -124,7 +124,7 @@ export interface LensServerConfig<
 // =============================================================================
 
 /** Field mode for entity fields */
-export type FieldMode = "exposed" | "resolve" | "subscribe";
+export type FieldMode = "exposed" | "resolve" | "subscribe" | "live";
 
 /** Entity field metadata for client-side routing decisions */
 export interface EntityFieldMetadata {