@sylphx/lens-server 2.5.0 → 2.6.0

package/dist/index.d.ts

@@ -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 {
@@ -614,7 +634,9 @@ interface LensServer {
 	getPluginManager(): PluginManager;
 	/**
 	* Check if any selected field (recursively) is a subscription.
-	* Used by handlers to determine if SSE/WS transport is needed.
+	*
+	* @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)
@@ -623,7 +645,10 @@ interface LensServer {
 	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.
+	*
+	* @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

package/dist/index.js

@@ -454,9 +454,28 @@ class LensServerImpl {
   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];
@@ -817,10 +836,28 @@ 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 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: opType,
@@ -830,7 +867,11 @@ class LensServerImpl {
       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.5.0",
+	"version": "2.6.0",
 	"description": "Server runtime for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",

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/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();
 	});
 });

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,
@@ -245,12 +249,15 @@ class LensServerImpl<
 	}
 
 	// =========================================================================
-	// Subscription Detection
+	// Subscription Detection (Deprecated - Use client-side with entities metadata)
 	// =========================================================================
 
 	/**
 	 * Check if any selected field (recursively) is a subscription.
-	 * Used to determine if SSE/WS transport is needed.
+	 *
+	 * @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)
@@ -310,6 +317,10 @@ class LensServerImpl<
 	/**
 	 * 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
@@ -352,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.
 	 *
@@ -996,13 +1035,34 @@ 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)) {
 			// 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: opType,
@@ -1013,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;
 }
 
 // =============================================================================
@@ -264,12 +287,14 @@ export interface LensServer {
 	getPluginManager(): PluginManager;
 
 	// =========================================================================
-	// Subscription Detection (Transport Selection)
+	// Subscription Detection (Deprecated - Use client-side with entities metadata)
 	// =========================================================================
 
 	/**
 	 * Check if any selected field (recursively) is a subscription.
-	 * Used by handlers to determine if SSE/WS transport is needed.
+	 *
+	 * @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)
@@ -279,7 +304,10 @@ export interface LensServer {
 
 	/**
 	 * Check if an operation requires streaming transport.
-	 * Returns true if operation uses async generator OR any selected field is subscription.
+	 *
+	 * @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