@sylphx/lens-server 2.7.1 → 2.8.0

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;
@@ -779,21 +780,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
-          };
-          result[field] = await resolverDef.resolveField(field, obj, args, extendedCtx);
+          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);
+          }
+          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);
     }
@@ -822,11 +870,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.1",
+	"version": "2.8.0",
 	"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.0"
 	},
 	"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

@@ -33,7 +33,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 +552,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)
@@ -941,26 +945,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!,
-					};
-					result[field] = await resolverDef.resolveField(field, obj, args, extendedCtx);
+					// 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);
+					}
+
+					// 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
+						}
+					}
+				} 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
@@ -1027,12 +1106,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 {