@sylphx/lens-server 2.4.0 → 2.5.0

package/dist/index.d.ts

@@ -249,7 +249,7 @@ interface EnhanceOperationMetaContext {
 	/** Operation path (e.g., 'user.create') */
 	path: string;
 	/** Operation type */
-	type: "query" | "mutation";
+	type: "query" | "mutation" | "subscription";
 	/** Current metadata (can be modified) */
 	meta: Record<string, unknown>;
 	/** Operation definition (MutationDef or QueryDef) */
@@ -612,6 +612,23 @@ interface LensServer {
 	* Get the plugin manager for direct hook access.
 	*/
 	getPluginManager(): PluginManager;
+	/**
+	* Check if any selected field (recursively) is a subscription.
+	* Used by handlers to determine if SSE/WS transport is needed.
+	*
+	* @param entityName - The entity type name
+	* @param select - Selection object (if undefined, checks ALL fields)
+	* @returns true if any selected field is a subscription
+	*/
+	hasAnySubscription(entityName: string, select?: SelectionObject): boolean;
+	/**
+	* Check if an operation requires streaming transport.
+	* Returns true if operation uses async generator OR any selected field is subscription.
+	*
+	* @param path - Operation path
+	* @param select - Selection object for return type fields
+	*/
+	requiresStreamingTransport(path: string, select?: SelectionObject): boolean;
 }
 type InferInput<T> = T extends QueryDef<infer I, any> ? I : T extends MutationDef<infer I, any> ? I : never;
 type InferOutput<T> = T extends QueryDef<any, infer O> ? O : T extends MutationDef<any, infer O> ? O : T extends FieldType<infer F> ? F : never;

package/dist/index.js

@@ -403,6 +403,54 @@ class LensServerImpl {
       }
     }
   }
+  hasAnySubscription(entityName, select, visited = new Set) {
+    if (visited.has(entityName))
+      return false;
+    visited.add(entityName);
+    const resolver = this.resolverMap?.get(entityName);
+    if (!resolver)
+      return false;
+    const fieldsToCheck = select ? Object.keys(select) : resolver.getFieldNames();
+    for (const fieldName of fieldsToCheck) {
+      if (!resolver.hasField(fieldName))
+        continue;
+      if (resolver.isSubscription(fieldName)) {
+        return true;
+      }
+      const fieldSelect = select?.[fieldName];
+      const nestedSelect = typeof fieldSelect === "object" && fieldSelect !== null && "select" in fieldSelect ? fieldSelect.select : undefined;
+      if (nestedSelect || typeof fieldSelect === "object" && fieldSelect !== null) {
+        for (const [targetEntityName] of this.resolverMap ?? []) {
+          if (targetEntityName === entityName)
+            continue;
+          if (this.hasAnySubscription(targetEntityName, nestedSelect, visited)) {
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+  requiresStreamingTransport(path, select) {
+    const def = this.queries[path] ?? this.mutations[path];
+    if (!def)
+      return false;
+    const resolverFn = def._resolve;
+    if (resolverFn) {
+      const fnName = resolverFn.constructor?.name;
+      if (fnName === "AsyncGeneratorFunction" || fnName === "GeneratorFunction") {
+        return true;
+      }
+    }
+    const returnType = def._output;
+    if (returnType && typeof returnType === "object" && "_name" in returnType) {
+      const entityName = returnType._name;
+      if (this.hasAnySubscription(entityName, select)) {
+        return true;
+      }
+    }
+    return false;
+  }
   getMetadata() {
     return {
       version: this.version,
@@ -770,10 +818,12 @@ class LensServerImpl {
       current[parts[parts.length - 1]] = meta;
     };
     for (const [name, def] of Object.entries(this.queries)) {
-      const meta = { type: "query" };
+      const isSubscription = def._resolve?.constructor?.name === "AsyncGeneratorFunction" || def._resolve?.constructor?.name === "GeneratorFunction";
+      const opType = isSubscription ? "subscription" : "query";
+      const meta = { type: opType };
       this.pluginManager.runEnhanceOperationMeta({
         path: name,
-        type: "query",
+        type: opType,
         meta,
         definition: def
       });
@@ -1179,13 +1229,7 @@ function createHandler(server, options = {}) {
   return result;
 }
 // src/handlers/framework.ts
-import { firstValueFrom as firstValueFrom2, isObservable } from "@sylphx/lens-core";
-async function resolveExecuteResult(result) {
-  if (isObservable(result)) {
-    return firstValueFrom2(result);
-  }
-  return result;
-}
+import { firstValueFrom as firstValueFrom2 } from "@sylphx/lens-core";
 function createServerClientProxy(server) {
   function createProxy(path) {
     return new Proxy(() => {}, {
@@ -1199,7 +1243,7 @@ function createServerClientProxy(server) {
       },
       async apply(_, __, args) {
         const input = args[0];
-        const result = await resolveExecuteResult(server.execute({ path, input }));
+        const result = await firstValueFrom2(server.execute({ path, input }));
         if (result.error) {
           throw result.error;
         }
@@ -1213,7 +1257,7 @@ async function handleWebQuery(server, path, url) {
   try {
     const inputParam = url.searchParams.get("input");
     const input = inputParam ? JSON.parse(inputParam) : undefined;
-    const result = await resolveExecuteResult(server.execute({ path, input }));
+    const result = await firstValueFrom2(server.execute({ path, input }));
     if (result.error) {
       return Response.json({ error: result.error.message }, { status: 400 });
     }
@@ -1226,7 +1270,7 @@ async function handleWebMutation(server, path, request) {
   try {
     const body = await request.json();
     const input = body.input;
-    const result = await resolveExecuteResult(server.execute({ path, input }));
+    const result = await firstValueFrom2(server.execute({ path, input }));
     if (result.error) {
       return Response.json({ error: result.error.message }, { status: 400 });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-server",
-	"version": "2.4.0",
+	"version": "2.5.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.2.0"
+		"@sylphx/lens-core": "^2.3.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",

package/src/handlers/framework.ts

@@ -37,21 +37,8 @@
  * ```
  */
 
-import { firstValueFrom, isObservable } from "@sylphx/lens-core";
+import { firstValueFrom } from "@sylphx/lens-core";
 import type { LensServer } from "../server/create.js";
-import type { LensResult } from "../server/types.js";
-
-/**
- * Helper to resolve server.execute() result which may be Observable or Promise.
- * This provides backwards compatibility for test mocks that return Promises.
- */
-async function resolveExecuteResult<T>(result: unknown): Promise<LensResult<T>> {
-	if (isObservable<LensResult<T>>(result)) {
-		return firstValueFrom(result);
-	}
-	// Handle Promise or direct value (for backwards compatibility with test mocks)
-	return result as Promise<LensResult<T>>;
-}
 
 // =============================================================================
 // Server Client Proxy
@@ -88,7 +75,7 @@ export function createServerClientProxy(server: LensServer): unknown {
 			},
 			async apply(_, __, args) {
 				const input = args[0];
-				const result = await resolveExecuteResult(server.execute({ path, input }));
+				const result = await firstValueFrom(server.execute({ path, input }));
 
 				if (result.error) {
 					throw result.error;
@@ -126,7 +113,7 @@ export async function handleWebQuery(
 		const inputParam = url.searchParams.get("input");
 		const input = inputParam ? JSON.parse(inputParam) : undefined;
 
-		const result = await resolveExecuteResult(server.execute({ path, input }));
+		const result = await firstValueFrom(server.execute({ path, input }));
 
 		if (result.error) {
 			return Response.json({ error: result.error.message }, { status: 400 });
@@ -161,7 +148,7 @@ export async function handleWebMutation(
 		const body = (await request.json()) as { input?: unknown };
 		const input = body.input;
 
-		const result = await resolveExecuteResult(server.execute({ path, input }));
+		const result = await firstValueFrom(server.execute({ path, input }));
 
 		if (result.error) {
 			return Response.json({ error: result.error.message }, { status: 400 });

package/src/plugin/types.ts

@@ -218,7 +218,7 @@ export interface EnhanceOperationMetaContext {
 	/** Operation path (e.g., 'user.create') */
 	path: string;
 	/** Operation type */
-	type: "query" | "mutation";
+	type: "query" | "mutation" | "subscription";
 	/** Current metadata (can be modified) */
 	meta: Record<string, unknown>;
 	/** Operation definition (MutationDef or QueryDef) */

package/src/server/create.test.ts

@@ -1274,3 +1274,204 @@ describe("observable error handling", () => {
 		expect(result.error?.message).toBe("Async error");
 	});
 });
+
+// =============================================================================
+// Test: Subscription Detection
+// =============================================================================
+
+describe("Subscription detection", () => {
+	// Test entity for subscription detection
+	const Profile = entity("Profile", {
+		id: t.id(),
+		name: t.string(),
+		status: t.string(),
+	});
+
+	describe("hasAnySubscription", () => {
+		it("returns false when no resolvers are configured", () => {
+			const server = createApp({
+				entities: { User },
+				queries: { getUser },
+			});
+
+			expect(server.hasAnySubscription("User")).toBe(false);
+		});
+
+		it("returns false when entity has only .resolve() fields", () => {
+			const userResolver = resolver(User, (f) => ({
+				id: f.expose("id"),
+				name: f.expose("name"),
+				displayName: f.string().resolve(({ parent }) => `User: ${parent.name}`),
+			}));
+
+			const server = createApp({
+				entities: { User },
+				queries: { getUser },
+				resolvers: [userResolver],
+			});
+
+			expect(server.hasAnySubscription("User")).toBe(false);
+		});
+
+		it("returns true when entity has a .subscribe() field", () => {
+			const profileResolver = resolver(Profile, (f) => ({
+				id: f.expose("id"),
+				name: f.expose("name"),
+				// Subscription field
+				status: f.string().subscribe(({ ctx }) => {
+					ctx.emit("online");
+				}),
+			}));
+
+			const server = createApp({
+				entities: { Profile },
+				queries: {
+					getProfile: query()
+						.input(z.object({ id: z.string() }))
+						.returns(Profile)
+						.resolve(({ input }) => ({ id: input.id, name: "Test", status: "online" })),
+				},
+				resolvers: [profileResolver],
+			});
+
+			expect(server.hasAnySubscription("Profile")).toBe(true);
+		});
+
+		it("returns false with select that excludes subscription field", () => {
+			const profileResolver = resolver(Profile, (f) => ({
+				id: f.expose("id"),
+				name: f.expose("name"),
+				status: f.string().subscribe(({ ctx }) => {
+					ctx.emit("online");
+				}),
+			}));
+
+			const server = createApp({
+				entities: { Profile },
+				queries: {
+					getProfile: query()
+						.input(z.object({ id: z.string() }))
+						.returns(Profile)
+						.resolve(({ input }) => ({ id: input.id, name: "Test", status: "online" })),
+				},
+				resolvers: [profileResolver],
+			});
+
+			// Only selecting non-subscription fields
+			expect(server.hasAnySubscription("Profile", { id: true, name: true })).toBe(false);
+		});
+
+		it("returns true with select that includes subscription field", () => {
+			const profileResolver = resolver(Profile, (f) => ({
+				id: f.expose("id"),
+				name: f.expose("name"),
+				status: f.string().subscribe(({ ctx }) => {
+					ctx.emit("online");
+				}),
+			}));
+
+			const server = createApp({
+				entities: { Profile },
+				queries: {
+					getProfile: query()
+						.input(z.object({ id: z.string() }))
+						.returns(Profile)
+						.resolve(({ input }) => ({ id: input.id, name: "Test", status: "online" })),
+				},
+				resolvers: [profileResolver],
+			});
+
+			// Selecting the subscription field
+			expect(server.hasAnySubscription("Profile", { id: true, status: true })).toBe(true);
+		});
+
+		it("returns false for unknown entity", () => {
+			const server = createApp({
+				entities: { User },
+				queries: { getUser },
+			});
+
+			expect(server.hasAnySubscription("UnknownEntity")).toBe(false);
+		});
+	});
+
+	describe("requiresStreamingTransport", () => {
+		it("returns false for regular query", () => {
+			const server = createApp({
+				entities: { User },
+				queries: { getUser },
+			});
+
+			expect(server.requiresStreamingTransport("getUser")).toBe(false);
+		});
+
+		it("returns true for async generator query", () => {
+			const streamQuery = query().subscribe(async function* () {
+				yield { count: 1 };
+				yield { count: 2 };
+			});
+
+			const server = createApp({
+				queries: { streamQuery },
+			});
+
+			expect(server.requiresStreamingTransport("streamQuery")).toBe(true);
+		});
+
+		it("returns false for unknown operation", () => {
+			const server = createApp({
+				queries: { getUser },
+			});
+
+			expect(server.requiresStreamingTransport("unknownOperation")).toBe(false);
+		});
+
+		it("returns true when return type has subscription fields", () => {
+			const profileResolver = resolver(Profile, (f) => ({
+				id: f.expose("id"),
+				name: f.expose("name"),
+				status: f.string().subscribe(({ ctx }) => {
+					ctx.emit("online");
+				}),
+			}));
+
+			const getProfile = query()
+				.input(z.object({ id: z.string() }))
+				.returns(Profile)
+				.resolve(({ input }) => ({ id: input.id, name: "Test", status: "online" }));
+
+			const server = createApp({
+				entities: { Profile },
+				queries: { getProfile },
+				resolvers: [profileResolver],
+			});
+
+			// No select - checks all fields
+			expect(server.requiresStreamingTransport("getProfile")).toBe(true);
+		});
+
+		it("returns false when select excludes subscription fields", () => {
+			const profileResolver = resolver(Profile, (f) => ({
+				id: f.expose("id"),
+				name: f.expose("name"),
+				status: f.string().subscribe(({ ctx }) => {
+					ctx.emit("online");
+				}),
+			}));
+
+			const getProfile = query()
+				.input(z.object({ id: z.string() }))
+				.returns(Profile)
+				.resolve(({ input }) => ({ id: input.id, name: "Test", status: "online" }));
+
+			const server = createApp({
+				entities: { Profile },
+				queries: { getProfile },
+				resolvers: [profileResolver],
+			});
+
+			// Only selecting non-subscription fields
+			expect(server.requiresStreamingTransport("getProfile", { id: true, name: true })).toBe(false);
+		});
+	});
+});

package/src/server/create.ts

@@ -244,6 +244,106 @@ class LensServerImpl<
 		}
 	}
 
+	// =========================================================================
+	// Subscription Detection
+	// =========================================================================
+
+	/**
+	 * Check if any selected field (recursively) is a subscription.
+	 * Used to determine if SSE/WS transport is needed.
+	 *
+	 * @param entityName - The entity type name
+	 * @param select - Selection object (if undefined, checks ALL fields)
+	 * @param visited - Set of visited entity names (prevents infinite recursion)
+	 * @returns true if any selected field is a subscription
+	 */
+	hasAnySubscription(
+		entityName: string,
+		select?: SelectionObject,
+		visited: Set<string> = new Set(),
+	): boolean {
+		// Prevent infinite recursion on circular references
+		if (visited.has(entityName)) return false;
+		visited.add(entityName);
+
+		const resolver = this.resolverMap?.get(entityName);
+		if (!resolver) return false;
+
+		// Determine which fields to check
+		const fieldsToCheck = select ? Object.keys(select) : (resolver.getFieldNames() as string[]);
+
+		for (const fieldName of fieldsToCheck) {
+			// Skip if field doesn't exist in resolver
+			if (!resolver.hasField(fieldName)) continue;
+
+			// Check if this field is a subscription
+			if (resolver.isSubscription(fieldName)) {
+				return true;
+			}
+
+			// Get nested selection for this field
+			const fieldSelect = select?.[fieldName];
+			const nestedSelect =
+				typeof fieldSelect === "object" && fieldSelect !== null && "select" in fieldSelect
+					? (fieldSelect as { select?: SelectionObject }).select
+					: undefined;
+
+			// For relation fields, recursively check the target entity
+			// We need to determine the target entity from the resolver's field definition
+			// For now, we use the selection to guide us - if there's nested selection,
+			// we try to find a matching entity resolver
+			if (nestedSelect || (typeof fieldSelect === "object" && fieldSelect !== null)) {
+				// Try to find target entity by checking all resolvers
+				// In a real scenario, we'd have field metadata linking to target entity
+				for (const [targetEntityName] of this.resolverMap ?? []) {
+					if (targetEntityName === entityName) continue; // Skip self
+					if (this.hasAnySubscription(targetEntityName, nestedSelect, visited)) {
+						return true;
+					}
+				}
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Check if an operation (and its return type's fields) requires streaming transport.
+	 *
+	 * Returns true if:
+	 * 1. Operation resolver is async generator (yields values)
+	 * 2. Operation resolver uses emit pattern
+	 * 3. Any selected field in the return type is a subscription
+	 *
+	 * @param path - Operation path
+	 * @param select - Selection object for return type fields
+	 */
+	requiresStreamingTransport(path: string, select?: SelectionObject): boolean {
+		const def = this.queries[path] ?? this.mutations[path];
+		if (!def) return false;
+
+		// Check 1: Operation-level subscription (async generator)
+		const resolverFn = def._resolve;
+		if (resolverFn) {
+			const fnName = resolverFn.constructor?.name;
+			if (fnName === "AsyncGeneratorFunction" || fnName === "GeneratorFunction") {
+				return true;
+			}
+		}
+
+		// Check 2 & 3: Field-level subscriptions
+		// Get the return entity type from operation metadata
+		const returnType = def._output;
+		if (returnType && typeof returnType === "object" && "_name" in returnType) {
+			const entityName = (returnType as { _name: string })._name;
+			if (this.hasAnySubscription(entityName, select)) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
 	// =========================================================================
 	// Core Methods
 	// =========================================================================
@@ -897,10 +997,15 @@ class LensServerImpl<
 		};
 
 		for (const [name, def] of Object.entries(this.queries)) {
-			const meta: OperationMeta = { type: "query" };
+			// Auto-detect subscription: if resolver is AsyncGeneratorFunction → subscription
+			const isSubscription =
+				def._resolve?.constructor?.name === "AsyncGeneratorFunction" ||
+				def._resolve?.constructor?.name === "GeneratorFunction";
+			const opType = isSubscription ? "subscription" : "query";
+			const meta: OperationMeta = { type: opType };
 			this.pluginManager.runEnhanceOperationMeta({
 				path: name,
-				type: "query",
+				type: opType,
 				meta: meta as unknown as Record<string, unknown>,
 				definition: def,
 			});

package/src/server/types.ts

@@ -262,6 +262,29 @@ export interface LensServer {
 	 * Get the plugin manager for direct hook access.
 	 */
 	getPluginManager(): PluginManager;
+
+	// =========================================================================
+	// Subscription Detection (Transport Selection)
+	// =========================================================================
+
+	/**
+	 * Check if any selected field (recursively) is a subscription.
+	 * Used by handlers to determine if SSE/WS transport is needed.
+	 *
+	 * @param entityName - The entity type name
+	 * @param select - Selection object (if undefined, checks ALL fields)
+	 * @returns true if any selected field is a subscription
+	 */
+	hasAnySubscription(entityName: string, select?: SelectionObject): boolean;
+
+	/**
+	 * Check if an operation requires streaming transport.
+	 * Returns true if operation uses async generator OR any selected field is subscription.
+	 *
+	 * @param path - Operation path
+	 * @param select - Selection object for return type fields
+	 */
+	requiresStreamingTransport(path: string, select?: SelectionObject): boolean;
 }
 
 // =============================================================================