@sylphx/lens-server 2.4.1 → 2.6.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) */
@@ -468,6 +468,11 @@ type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
 interface OperationMeta {
 	type: "query" | "mutation" | "subscription";
 	optimistic?: OptimisticDSL;
+	/**
+	* Return entity type name (if operation returns an entity).
+	* Used by client for field-level subscription detection.
+	*/
+	returnType?: string;
 }
 /** Nested operations structure for handshake */
 type OperationsMap = {
@@ -506,10 +511,25 @@ interface LensServerConfig<
 	*/
 	plugins?: ServerPlugin[] | undefined;
 }
+/** Field mode for entity fields */
+type FieldMode = "exposed" | "resolve" | "subscribe";
+/** Entity field metadata for client-side routing decisions */
+interface EntityFieldMetadata {
+	[fieldName: string]: FieldMode;
+}
+/** All entities field metadata */
+interface EntitiesMetadata {
+	[entityName: string]: EntityFieldMetadata;
+}
 /** Server metadata for transport handshake */
 interface ServerMetadata {
 	version: string;
 	operations: OperationsMap;
+	/**
+	* Entity field metadata for client-side transport routing.
+	* Client uses this to determine if any selected field requires streaming transport.
+	*/
+	entities: EntitiesMetadata;
 }
 /** Operation for execution */
 interface LensOperation {
@@ -612,6 +632,28 @@ interface LensServer {
 	* Get the plugin manager for direct hook access.
 	*/
 	getPluginManager(): PluginManager;
+	/**
+	* Check if any selected field (recursively) is a subscription.
+	*
+	* @deprecated Use client-side subscription detection with `getMetadata().entities` instead.
+	* The client should use the entities metadata to determine transport routing.
+	*
+	* @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.
+	*
+	* @deprecated Use client-side transport detection with `getMetadata().entities` instead.
+	* The client should determine transport based on operation type from metadata
+	* and entity field modes.
+	*
+	* @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,12 +403,79 @@ 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,
-      operations: this.buildOperationsMap()
+      operations: this.buildOperationsMap(),
+      entities: this.buildEntitiesMetadata()
     };
   }
+  buildEntitiesMetadata() {
+    const result = {};
+    if (!this.resolverMap)
+      return result;
+    for (const [entityName, resolver] of this.resolverMap) {
+      const fieldMetadata = {};
+      for (const fieldName of resolver.getFieldNames()) {
+        const mode = resolver.getFieldMode(String(fieldName));
+        if (mode) {
+          fieldMetadata[String(fieldName)] = mode;
+        }
+      }
+      if (Object.keys(fieldMetadata).length > 0) {
+        result[entityName] = fieldMetadata;
+      }
+    }
+    return result;
+  }
   execute(op) {
     const { path, input } = op;
     const isQuery = !!this.queries[path];
@@ -769,18 +836,42 @@ class LensServerImpl {
       }
       current[parts[parts.length - 1]] = meta;
     };
+    const getReturnTypeName = (output) => {
+      if (!output)
+        return;
+      if (Array.isArray(output) && output.length > 0) {
+        const element = output[0];
+        if (element && typeof element === "object" && "_name" in element) {
+          return element._name;
+        }
+      }
+      if (typeof output === "object" && "_name" in output) {
+        return output._name;
+      }
+      return;
+    };
     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 returnType = getReturnTypeName(def._output);
+      const meta = { type: opType };
+      if (returnType) {
+        meta.returnType = returnType;
+      }
       this.pluginManager.runEnhanceOperationMeta({
         path: name,
-        type: "query",
+        type: opType,
         meta,
         definition: def
       });
       setNested(name, meta);
     }
     for (const [name, def] of Object.entries(this.mutations)) {
+      const returnType = getReturnTypeName(def._output);
       const meta = { type: "mutation" };
+      if (returnType) {
+        meta.returnType = returnType;
+      }
       this.pluginManager.runEnhanceOperationMeta({
         path: name,
         type: "mutation",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-server",
-	"version": "2.4.1",
+	"version": "2.6.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/e2e/server.test.ts

@@ -448,7 +448,8 @@ describe("E2E - Metadata", () => {
 		const metadata = server.getMetadata();
 
 		expect(metadata.version).toBe("2.0.0");
-		expect(metadata.operations.getUser).toEqual({ type: "query" });
+		expect(metadata.operations.getUser.type).toBe("query");
+		expect(metadata.operations.getUser.returnType).toBe("User"); // Now includes returnType
 		expect(metadata.operations.createUser.type).toBe("mutation");
 		// createUser should have auto-derived optimistic hint (with plugin)
 		expect(metadata.operations.createUser.optimistic).toBeDefined();

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

@@ -127,8 +127,9 @@ describe("getMetadata", () => {
 		const metadata = server.getMetadata();
 
 		expect(metadata.version).toBe("1.2.3");
-		expect(metadata.operations.getUser).toEqual({ type: "query" });
-		expect(metadata.operations.getUsers).toEqual({ type: "query" });
+		expect(metadata.operations.getUser.type).toBe("query");
+		expect(metadata.operations.getUser.returnType).toBe("User"); // Now includes returnType
+		expect(metadata.operations.getUsers.type).toBe("query");
 		expect(metadata.operations.createUser.type).toBe("mutation");
 		expect(metadata.operations.updateUser.type).toBe("mutation");
 	});
@@ -175,7 +176,8 @@ describe("getMetadata", () => {
 		const metadata = server.getMetadata();
 
 		expect(metadata.operations.user).toBeDefined();
-		expect((metadata.operations.user as Record<string, unknown>).get).toEqual({ type: "query" });
+		expect((metadata.operations.user as Record<string, Record<string, unknown>>).get.type).toBe("query");
+		expect((metadata.operations.user as Record<string, Record<string, unknown>>).get.returnType).toBe("User");
 		expect((metadata.operations.user as Record<string, unknown>).create).toBeDefined();
 	});
 });
@@ -1274,3 +1276,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

@@ -47,6 +47,8 @@ import { applySelection, extractNestedInputs } from "./selection.js";
 import type {
 	ClientSendFn,
 	EntitiesMap,
+	EntitiesMetadata,
+	EntityFieldMetadata,
 	LensLogger,
 	LensOperation,
 	LensResult,
@@ -66,6 +68,8 @@ import type {
 export type {
 	ClientSendFn,
 	EntitiesMap,
+	EntitiesMetadata,
+	EntityFieldMetadata,
 	InferApi,
 	InferInput,
 	InferOutput,
@@ -244,6 +248,113 @@ class LensServerImpl<
 		}
 	}
 
+	// =========================================================================
+	// Subscription Detection (Deprecated - Use client-side with entities metadata)
+	// =========================================================================
+
+	/**
+	 * Check if any selected field (recursively) is a subscription.
+	 *
+	 * @deprecated Use client-side subscription detection with `getMetadata().entities` instead.
+	 * The client should use the entities metadata to determine transport routing.
+	 * This method remains for backwards compatibility but will be removed in a future version.
+	 *
+	 * @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.
+	 *
+	 * @deprecated Use client-side transport detection with `getMetadata().entities` instead.
+	 * The client should determine transport based on operation type from metadata
+	 * and entity field modes. This method remains for backwards compatibility.
+	 *
+	 * 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
 	// =========================================================================
@@ -252,9 +363,37 @@ class LensServerImpl<
 		return {
 			version: this.version,
 			operations: this.buildOperationsMap(),
+			entities: this.buildEntitiesMetadata(),
 		};
 	}
 
+	/**
+	 * Build entities metadata for client-side transport routing.
+	 * Maps each entity to its field modes (exposed/resolve/subscribe).
+	 */
+	private buildEntitiesMetadata(): EntitiesMetadata {
+		const result: EntitiesMetadata = {};
+
+		if (!this.resolverMap) return result;
+
+		for (const [entityName, resolver] of this.resolverMap) {
+			const fieldMetadata: EntityFieldMetadata = {};
+
+			for (const fieldName of resolver.getFieldNames()) {
+				const mode = resolver.getFieldMode(String(fieldName));
+				if (mode) {
+					fieldMetadata[String(fieldName)] = mode;
+				}
+			}
+
+			if (Object.keys(fieldMetadata).length > 0) {
+				result[entityName] = fieldMetadata;
+			}
+		}
+
+		return result;
+	}
+
 	/**
 	 * Execute operation and return Observable.
 	 *
@@ -896,11 +1035,37 @@ class LensServerImpl<
 			current[parts[parts.length - 1]] = meta;
 		};
 
+		// Helper to extract return type name from output definition
+		const getReturnTypeName = (output: unknown): string | undefined => {
+			if (!output) return undefined;
+			// Handle array output: [EntityDef] → extract from first element
+			if (Array.isArray(output) && output.length > 0) {
+				const element = output[0];
+				if (element && typeof element === "object" && "_name" in element) {
+					return element._name as string;
+				}
+			}
+			// Handle direct entity output
+			if (typeof output === "object" && "_name" in output) {
+				return (output as { _name?: string })._name;
+			}
+			return undefined;
+		};
+
 		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 returnType = getReturnTypeName(def._output);
+			const meta: OperationMeta = { type: opType };
+			if (returnType) {
+				meta.returnType = returnType;
+			}
 			this.pluginManager.runEnhanceOperationMeta({
 				path: name,
-				type: "query",
+				type: opType,
 				meta: meta as unknown as Record<string, unknown>,
 				definition: def,
 			});
@@ -908,7 +1073,11 @@ class LensServerImpl<
 		}
 
 		for (const [name, def] of Object.entries(this.mutations)) {
+			const returnType = getReturnTypeName(def._output);
 			const meta: OperationMeta = { type: "mutation" };
+			if (returnType) {
+				meta.returnType = returnType;
+			}
 			this.pluginManager.runEnhanceOperationMeta({
 				path: name,
 				type: "mutation",

package/src/server/types.ts

@@ -64,6 +64,11 @@ export type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
 export interface OperationMeta {
 	type: "query" | "mutation" | "subscription";
 	optimistic?: OptimisticDSL;
+	/**
+	 * Return entity type name (if operation returns an entity).
+	 * Used by client for field-level subscription detection.
+	 */
+	returnType?: string;
 }
 
 /** Nested operations structure for handshake */
@@ -118,10 +123,28 @@ export interface LensServerConfig<
 // Server Metadata
 // =============================================================================
 
+/** Field mode for entity fields */
+export type FieldMode = "exposed" | "resolve" | "subscribe";
+
+/** Entity field metadata for client-side routing decisions */
+export interface EntityFieldMetadata {
+	[fieldName: string]: FieldMode;
+}
+
+/** All entities field metadata */
+export interface EntitiesMetadata {
+	[entityName: string]: EntityFieldMetadata;
+}
+
 /** Server metadata for transport handshake */
 export interface ServerMetadata {
 	version: string;
 	operations: OperationsMap;
+	/**
+	 * Entity field metadata for client-side transport routing.
+	 * Client uses this to determine if any selected field requires streaming transport.
+	 */
+	entities: EntitiesMetadata;
 }
 
 // =============================================================================
@@ -262,6 +285,34 @@ export interface LensServer {
 	 * Get the plugin manager for direct hook access.
 	 */
 	getPluginManager(): PluginManager;
+
+	// =========================================================================
+	// Subscription Detection (Deprecated - Use client-side with entities metadata)
+	// =========================================================================
+
+	/**
+	 * Check if any selected field (recursively) is a subscription.
+	 *
+	 * @deprecated Use client-side subscription detection with `getMetadata().entities` instead.
+	 * The client should use the entities metadata to determine transport routing.
+	 *
+	 * @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.
+	 *
+	 * @deprecated Use client-side transport detection with `getMetadata().entities` instead.
+	 * The client should determine transport based on operation type from metadata
+	 * and entity field modes.
+	 *
+	 * @param path - Operation path
+	 * @param select - Selection object for return type fields
+	 */
+	requiresStreamingTransport(path: string, select?: SelectionObject): boolean;
 }
 
 // =============================================================================