@sylphx/lens-server 1.5.2 → 1.11.0

package/dist/index.d.ts

@@ -238,21 +238,21 @@ interface LensServerConfig<
 	TRouter extends RouterDef = RouterDef
 > {
 	/** Entity definitions */
-	entities?: EntitiesMap;
+	entities?: EntitiesMap | undefined;
 	/** Router definition (namespaced operations) - context type is inferred */
-	router?: TRouter;
+	router?: TRouter | undefined;
 	/** Query definitions (flat, legacy) */
-	queries?: QueriesMap;
+	queries?: QueriesMap | undefined;
 	/** Mutation definitions (flat, legacy) */
-	mutations?: MutationsMap;
+	mutations?: MutationsMap | undefined;
 	/** Field resolvers array (use lens() factory to create) */
-	resolvers?: Resolvers;
+	resolvers?: Resolvers | undefined;
 	/** Logger for server messages (default: silent) */
-	logger?: LensLogger;
+	logger?: LensLogger | undefined;
 	/** Context factory - must return the context type expected by the router */
-	context?: (req?: unknown) => TContext | Promise<TContext>;
+	context?: ((req?: unknown) => TContext | Promise<TContext>) | undefined;
 	/** Server version */
-	version?: string;
+	version?: string | undefined;
 }
 /** Server metadata for transport handshake */
 interface ServerMetadata {

package/dist/index.js

@@ -11,7 +11,9 @@ import {
   createEmit,
   createUpdate as createUpdate2,
   flattenRouter,
+  isEntityDef,
   isMutationDef,
+  isPipeline,
   isQueryDef,
   runWithContext,
   toResolverMap
@@ -457,6 +459,70 @@ function createGraphStateManager(config) {
 }
 
 // src/server/create.ts
+function getEntityTypeName(returnSpec) {
+  if (!returnSpec)
+    return;
+  if (isEntityDef(returnSpec)) {
+    return returnSpec._name;
+  }
+  if (Array.isArray(returnSpec) && returnSpec.length === 1 && isEntityDef(returnSpec[0])) {
+    return returnSpec[0]._name;
+  }
+  return;
+}
+function getInputFields(inputSchema) {
+  if (!inputSchema?.shape)
+    return [];
+  return Object.keys(inputSchema.shape);
+}
+function sugarToPipeline(optimistic, entityType, inputFields) {
+  if (isPipeline(optimistic)) {
+    return optimistic;
+  }
+  if (!entityType) {
+    return optimistic;
+  }
+  if (optimistic === "merge") {
+    const args = { type: entityType };
+    for (const field of inputFields) {
+      args[field] = { $input: field };
+    }
+    return {
+      $pipe: [{ $do: "entity.update", $with: args }]
+    };
+  }
+  if (optimistic === "create") {
+    const args = { type: entityType, id: { $temp: true } };
+    for (const field of inputFields) {
+      if (field !== "id") {
+        args[field] = { $input: field };
+      }
+    }
+    return {
+      $pipe: [{ $do: "entity.create", $with: args }]
+    };
+  }
+  if (optimistic === "delete") {
+    return {
+      $pipe: [{ $do: "entity.delete", $with: { type: entityType, id: { $input: "id" } } }]
+    };
+  }
+  if (typeof optimistic === "object" && optimistic !== null && "merge" in optimistic && typeof optimistic.merge === "object") {
+    const extra = optimistic.merge;
+    const args = { type: entityType };
+    for (const field of inputFields) {
+      args[field] = { $input: field };
+    }
+    for (const [key, value] of Object.entries(extra)) {
+      args[key] = value;
+    }
+    return {
+      $pipe: [{ $do: "entity.update", $with: args }]
+    };
+  }
+  return optimistic;
+}
+
 class DataLoader {
   batchFn;
   batch = new Map;
@@ -627,7 +693,9 @@ class LensServerImpl {
     for (const [name, def] of Object.entries(this.mutations)) {
       const meta = { type: "mutation" };
       if (def._optimistic) {
-        meta.optimistic = def._optimistic;
+        const entityType = getEntityTypeName(def._output);
+        const inputFields = getInputFields(def._input);
+        meta.optimistic = sugarToPipeline(def._optimistic, entityType, inputFields);
       }
       setNested(name, meta);
     }
@@ -783,11 +851,14 @@ class LensServerImpl {
             sub.cleanups.splice(idx, 1);
         };
       };
-      const result = resolver({
-        input: sub.input,
-        ctx: context,
+      const lensContext = {
+        ...context,
         emit,
         onCleanup
+      };
+      const result = resolver({
+        input: sub.input,
+        ctx: lensContext
       });
       if (isAsyncIterable(result)) {
         for await (const value of result) {
@@ -938,11 +1009,14 @@ class LensServerImpl {
         }
         const emit = createEmit(() => {});
         const onCleanup = () => () => {};
-        const result = resolver({
-          input: cleanInput,
-          ctx: context,
+        const lensContext = {
+          ...context,
           emit,
           onCleanup
+        };
+        const result = resolver({
+          input: cleanInput,
+          ctx: lensContext
         });
         let data;
         if (isAsyncIterable(result)) {
@@ -982,11 +1056,14 @@ class LensServerImpl {
         }
         const emit = createEmit(() => {});
         const onCleanup = () => () => {};
-        const result = await resolver({
-          input,
-          ctx: context,
+        const lensContext = {
+          ...context,
           emit,
           onCleanup
+        };
+        const result = await resolver({
+          input,
+          ctx: lensContext
         });
         const entityName = this.getEntityNameFromMutation(name);
         const entities = this.extractEntities(entityName, result);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-server",
-	"version": "1.5.2",
+	"version": "1.11.0",
 	"description": "Server runtime for Lens API framework",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -15,7 +15,7 @@
 		"build": "bunup",
 		"typecheck": "tsc --noEmit",
 		"test": "bun test",
-		"prepack": "bun run build"
+		"prepack": "[ -d dist ] || bun run build"
 	},
 	"files": [
 		"dist",
@@ -30,7 +30,7 @@
 	"author": "SylphxAI",
 	"license": "MIT",
 	"dependencies": {
-		"@sylphx/lens-core": "^1.11.0"
+		"@sylphx/lens-core": "^1.22.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",

package/src/e2e/server.test.ts

@@ -317,8 +317,8 @@ describe("E2E - Subscriptions", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, emit }) => {
-				emitFn = emit;
+			.resolve(({ input, ctx }) => {
+				emitFn = ctx.emit;
 				const user = mockUsers.find((u) => u.id === input.id);
 				if (!user) throw new Error("Not found");
 				return user;
@@ -362,8 +362,8 @@ describe("E2E - Subscriptions", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, emit }) => {
-				emitFn = emit;
+			.resolve(({ input, ctx }) => {
+				emitFn = ctx.emit;
 				const user = mockUsers.find((u) => u.id === input.id);
 				if (!user) throw new Error("Not found");
 				return user;
@@ -464,8 +464,8 @@ describe("E2E - Cleanup", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, onCleanup }) => {
-				onCleanup(() => {
+			.resolve(({ input, ctx }) => {
+				ctx.onCleanup(() => {
 					cleanedUp = true;
 				});
 				const user = mockUsers.find((u) => u.id === input.id);
@@ -506,8 +506,8 @@ describe("E2E - GraphStateManager", () => {
 		const getUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, emit }) => {
-				emitFn = emit;
+			.resolve(({ input, ctx }) => {
+				emitFn = ctx.emit;
 				const user = mockUsers.find((u) => u.id === input.id);
 				if (!user) throw new Error("Not found");
 				return user;

package/src/index.ts

@@ -50,7 +50,7 @@ export {
 	// Metadata types (for transport handshake)
 	type ServerMetadata,
 	type WebSocketLike,
-} from "./server/create";
+} from "./server/create.js";
 
 // =============================================================================
 // State Management
@@ -68,7 +68,7 @@ export {
 	type StateFullMessage,
 	type StateUpdateMessage,
 	type Subscription,
-} from "./state";
+} from "./state/index.js";
 
 // =============================================================================
 // SSE Transport Adapter
@@ -82,4 +82,4 @@ export {
 	SSEHandler,
 	// Types
 	type SSEHandlerConfig,
-} from "./sse/handler";
+} from "./sse/handler.js";

package/src/server/create.test.ts

@@ -724,8 +724,8 @@ describe("onCleanup", () => {
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ onCleanup }) => {
-				onCleanup(() => {
+			.resolve(({ ctx }) => {
+				ctx.onCleanup(() => {
 					cleanedUp = true;
 				});
 				return mockUsers[0];
@@ -764,8 +764,8 @@ describe("onCleanup", () => {
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ onCleanup }) => {
-				onCleanup(() => {
+			.resolve(({ ctx }) => {
+				ctx.onCleanup(() => {
 					cleanedUp = true;
 				});
 				return mockUsers[0];
@@ -802,8 +802,8 @@ describe("onCleanup", () => {
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ onCleanup }) => {
-				const remove = onCleanup(() => {
+			.resolve(({ ctx }) => {
+				const remove = ctx.onCleanup(() => {
 					cleanedUp = true;
 				});
 				// Remove the cleanup before unsubscribe
@@ -950,8 +950,10 @@ describe("getMetadata", () => {
 		expect(metadata.version).toBe("1.2.3");
 		expect(metadata.operations).toBeDefined();
 		expect(metadata.operations.getUser).toEqual({ type: "query" });
-		// createUser auto-derives optimistic "create" from naming convention
-		expect(metadata.operations.createUser).toEqual({ type: "mutation", optimistic: "create" });
+		// createUser auto-derives optimistic "create" from naming convention (converted to Pipeline)
+		expect((metadata.operations.createUser as any).type).toBe("mutation");
+		expect((metadata.operations.createUser as any).optimistic.$pipe).toBeDefined();
+		expect((metadata.operations.createUser as any).optimistic.$pipe[0].$do).toBe("entity.create");
 	});
 
 	it("builds nested operations map from namespaced routes", () => {
@@ -973,8 +975,10 @@ describe("getMetadata", () => {
 		const metadata = server.getMetadata();
 		expect(metadata.operations.user).toBeDefined();
 		expect((metadata.operations.user as any).get).toEqual({ type: "query" });
-		// Auto-derives optimistic "create" from naming convention
-		expect((metadata.operations.user as any).create).toEqual({ type: "mutation", optimistic: "create" });
+		// Auto-derives optimistic "create" from naming convention (converted to Pipeline)
+		expect((metadata.operations.user as any).create.type).toBe("mutation");
+		expect((metadata.operations.user as any).create.optimistic.$pipe).toBeDefined();
+		expect((metadata.operations.user as any).create.optimistic.$pipe[0].$do).toBe("entity.create");
 	});
 
 	it("includes optimistic config in mutation metadata", () => {
@@ -990,9 +994,21 @@ describe("getMetadata", () => {
 		});
 
 		const metadata = server.getMetadata();
+		// Sugar "merge" is converted to Reify Pipeline
 		expect(metadata.operations.updateUser).toEqual({
 			type: "mutation",
-			optimistic: "merge",
+			optimistic: {
+				$pipe: [
+					{
+						$do: "entity.update",
+						$with: {
+							type: "User",
+							id: { $input: "id" },
+							name: { $input: "name" },
+						},
+					},
+				],
+			},
 		});
 	});
 
@@ -1499,8 +1515,8 @@ describe("Logger integration", () => {
 		const errorLogs: string[] = [];
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ onCleanup }) => {
-				onCleanup(() => {
+			.resolve(({ ctx }) => {
+				ctx.onCleanup(() => {
 					throw new Error("Cleanup failed");
 				});
 				return mockUsers[0];
@@ -1544,8 +1560,8 @@ describe("Logger integration", () => {
 		const errorLogs: string[] = [];
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ onCleanup }) => {
-				onCleanup(() => {
+			.resolve(({ ctx }) => {
+				ctx.onCleanup(() => {
 					throw new Error("Disconnect cleanup failed");
 				});
 				return mockUsers[0];
@@ -1584,6 +1600,567 @@ describe("Logger integration", () => {
 	});
 });
 
+// =============================================================================
+// Test: DataLoader Batching
+// =============================================================================
+
+describe("DataLoader Batching", () => {
+	it("batches multiple load calls into single batch function call", async () => {
+		let batchCallCount = 0;
+		let receivedKeys: string[] = [];
+
+		class TestDataLoader {
+			private batch: Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }[]> = new Map();
+			private scheduled = false;
+
+			constructor(private batchFn: (keys: string[]) => Promise<(string | null)[]>) {}
+
+			async load(key: string): Promise<string | null> {
+				return new Promise((resolve, reject) => {
+					const existing = this.batch.get(key);
+					if (existing) {
+						existing.push({ resolve, reject });
+					} else {
+						this.batch.set(key, [{ resolve, reject }]);
+					}
+					this.scheduleDispatch();
+				});
+			}
+
+			private scheduleDispatch(): void {
+				if (this.scheduled) return;
+				this.scheduled = true;
+				queueMicrotask(() => this.dispatch());
+			}
+
+			private async dispatch(): Promise<void> {
+				this.scheduled = false;
+				const batch = this.batch;
+				this.batch = new Map();
+
+				const keys = Array.from(batch.keys());
+				if (keys.length === 0) return;
+
+				try {
+					const results = await this.batchFn(keys);
+					keys.forEach((key, index) => {
+						const callbacks = batch.get(key)!;
+						const result = results[index] ?? null;
+						for (const { resolve } of callbacks) resolve(result);
+					});
+				} catch (error) {
+					for (const callbacks of batch.values()) {
+						for (const { reject } of callbacks) reject(error as Error);
+					}
+				}
+			}
+
+			clear(): void {
+				this.batch.clear();
+			}
+		}
+
+		const loader = new TestDataLoader(async (keys) => {
+			batchCallCount++;
+			receivedKeys = keys;
+			return keys.map((k) => `value-${k}`);
+		});
+
+		// Load multiple keys in same tick
+		const promises = [loader.load("key1"), loader.load("key2"), loader.load("key3")];
+
+		const results = await Promise.all(promises);
+
+		// Should batch all calls into single batch function call
+		expect(batchCallCount).toBe(1);
+		expect(receivedKeys).toEqual(["key1", "key2", "key3"]);
+		expect(results).toEqual(["value-key1", "value-key2", "value-key3"]);
+	});
+
+	it("handles duplicate keys in same batch", async () => {
+		class TestDataLoader {
+			private batch: Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }[]> = new Map();
+			private scheduled = false;
+
+			constructor(private batchFn: (keys: string[]) => Promise<(string | null)[]>) {}
+
+			async load(key: string): Promise<string | null> {
+				return new Promise((resolve, reject) => {
+					const existing = this.batch.get(key);
+					if (existing) {
+						existing.push({ resolve, reject });
+					} else {
+						this.batch.set(key, [{ resolve, reject }]);
+					}
+					this.scheduleDispatch();
+				});
+			}
+
+			private scheduleDispatch(): void {
+				if (this.scheduled) return;
+				this.scheduled = true;
+				queueMicrotask(() => this.dispatch());
+			}
+
+			private async dispatch(): Promise<void> {
+				this.scheduled = false;
+				const batch = this.batch;
+				this.batch = new Map();
+
+				const keys = Array.from(batch.keys());
+				if (keys.length === 0) return;
+
+				try {
+					const results = await this.batchFn(keys);
+					keys.forEach((key, index) => {
+						const callbacks = batch.get(key)!;
+						const result = results[index] ?? null;
+						for (const { resolve } of callbacks) resolve(result);
+					});
+				} catch (error) {
+					for (const callbacks of batch.values()) {
+						for (const { reject } of callbacks) reject(error as Error);
+					}
+				}
+			}
+
+			clear(): void {
+				this.batch.clear();
+			}
+		}
+
+		const loader = new TestDataLoader(async (keys) => {
+			return keys.map((k) => `value-${k}`);
+		});
+
+		// Load same key multiple times
+		const promises = [loader.load("key1"), loader.load("key1"), loader.load("key1")];
+
+		const results = await Promise.all(promises);
+
+		// All should resolve with same value
+		expect(results).toEqual(["value-key1", "value-key1", "value-key1"]);
+	});
+
+	it("handles batch function errors", async () => {
+		class TestDataLoader {
+			private batch: Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }[]> = new Map();
+			private scheduled = false;
+
+			constructor(private batchFn: (keys: string[]) => Promise<(string | null)[]>) {}
+
+			async load(key: string): Promise<string | null> {
+				return new Promise((resolve, reject) => {
+					const existing = this.batch.get(key);
+					if (existing) {
+						existing.push({ resolve, reject });
+					} else {
+						this.batch.set(key, [{ resolve, reject }]);
+					}
+					this.scheduleDispatch();
+				});
+			}
+
+			private scheduleDispatch(): void {
+				if (this.scheduled) return;
+				this.scheduled = true;
+				queueMicrotask(() => this.dispatch());
+			}
+
+			private async dispatch(): Promise<void> {
+				this.scheduled = false;
+				const batch = this.batch;
+				this.batch = new Map();
+
+				const keys = Array.from(batch.keys());
+				if (keys.length === 0) return;
+
+				try {
+					const results = await this.batchFn(keys);
+					keys.forEach((key, index) => {
+						const callbacks = batch.get(key)!;
+						const result = results[index] ?? null;
+						for (const { resolve } of callbacks) resolve(result);
+					});
+				} catch (error) {
+					for (const callbacks of batch.values()) {
+						for (const { reject } of callbacks) reject(error as Error);
+					}
+				}
+			}
+
+			clear(): void {
+				this.batch.clear();
+			}
+		}
+
+		const loader = new TestDataLoader(async () => {
+			throw new Error("Batch function error");
+		});
+
+		const promises = [loader.load("key1"), loader.load("key2")];
+
+		// All loads should reject with same error
+		await expect(Promise.all(promises)).rejects.toThrow("Batch function error");
+	});
+
+	it("does not schedule dispatch twice if already scheduled", async () => {
+		let dispatchCount = 0;
+
+		class TestDataLoader {
+			private batch: Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }[]> = new Map();
+			private scheduled = false;
+
+			constructor(private batchFn: (keys: string[]) => Promise<(string | null)[]>) {}
+
+			async load(key: string): Promise<string | null> {
+				return new Promise((resolve, reject) => {
+					const existing = this.batch.get(key);
+					if (existing) {
+						existing.push({ resolve, reject });
+					} else {
+						this.batch.set(key, [{ resolve, reject }]);
+					}
+					this.scheduleDispatch();
+				});
+			}
+
+			private scheduleDispatch(): void {
+				if (this.scheduled) return;
+				this.scheduled = true;
+				queueMicrotask(() => this.dispatch());
+			}
+
+			private async dispatch(): Promise<void> {
+				dispatchCount++;
+				this.scheduled = false;
+				const batch = this.batch;
+				this.batch = new Map();
+
+				const keys = Array.from(batch.keys());
+				if (keys.length === 0) return;
+
+				try {
+					const results = await this.batchFn(keys);
+					keys.forEach((key, index) => {
+						const callbacks = batch.get(key)!;
+						const result = results[index] ?? null;
+						for (const { resolve } of callbacks) resolve(result);
+					});
+				} catch (error) {
+					for (const callbacks of batch.values()) {
+						for (const { reject } of callbacks) reject(error as Error);
+					}
+				}
+			}
+
+			clear(): void {
+				this.batch.clear();
+			}
+		}
+
+		const loader = new TestDataLoader(async (keys) => {
+			return keys.map((k) => `value-${k}`);
+		});
+
+		// Load multiple keys
+		await Promise.all([loader.load("key1"), loader.load("key2"), loader.load("key3")]);
+
+		// Should only dispatch once despite multiple load calls
+		expect(dispatchCount).toBe(1);
+	});
+
+	it("clears pending batches when clear is called", () => {
+		class TestDataLoader {
+			private batch: Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }[]> = new Map();
+			private scheduled = false;
+
+			constructor(private batchFn: (keys: string[]) => Promise<(string | null)[]>) {}
+
+			async load(key: string): Promise<string | null> {
+				return new Promise((resolve, reject) => {
+					const existing = this.batch.get(key);
+					if (existing) {
+						existing.push({ resolve, reject });
+					} else {
+						this.batch.set(key, [{ resolve, reject }]);
+					}
+					this.scheduleDispatch();
+				});
+			}
+
+			private scheduleDispatch(): void {
+				if (this.scheduled) return;
+				this.scheduled = true;
+				queueMicrotask(() => this.dispatch());
+			}
+
+			private async dispatch(): Promise<void> {
+				this.scheduled = false;
+				const batch = this.batch;
+				this.batch = new Map();
+
+				const keys = Array.from(batch.keys());
+				if (keys.length === 0) return;
+
+				try {
+					const results = await this.batchFn(keys);
+					keys.forEach((key, index) => {
+						const callbacks = batch.get(key)!;
+						const result = results[index] ?? null;
+						for (const { resolve } of callbacks) resolve(result);
+					});
+				} catch (error) {
+					for (const callbacks of batch.values()) {
+						for (const { reject } of callbacks) reject(error as Error);
+					}
+				}
+			}
+
+			clear(): void {
+				this.batch.clear();
+			}
+
+			getBatchSize(): number {
+				return this.batch.size;
+			}
+		}
+
+		const loader = new TestDataLoader(async (keys) => {
+			return keys.map((k) => `value-${k}`);
+		});
+
+		// Add some items to batch (but don't await - they won't dispatch yet)
+		loader.load("key1");
+		loader.load("key2");
+
+		// Clear should remove pending items
+		loader.clear();
+
+		// Batch should be empty
+		expect(loader.getBatchSize()).toBe(0);
+	});
+
+	it("handles null results from batch function", async () => {
+		class TestDataLoader {
+			private batch: Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }[]> = new Map();
+			private scheduled = false;
+
+			constructor(private batchFn: (keys: string[]) => Promise<(string | null)[]>) {}
+
+			async load(key: string): Promise<string | null> {
+				return new Promise((resolve, reject) => {
+					const existing = this.batch.get(key);
+					if (existing) {
+						existing.push({ resolve, reject });
+					} else {
+						this.batch.set(key, [{ resolve, reject }]);
+					}
+					this.scheduleDispatch();
+				});
+			}
+
+			private scheduleDispatch(): void {
+				if (this.scheduled) return;
+				this.scheduled = true;
+				queueMicrotask(() => this.dispatch());
+			}
+
+			private async dispatch(): Promise<void> {
+				this.scheduled = false;
+				const batch = this.batch;
+				this.batch = new Map();
+
+				const keys = Array.from(batch.keys());
+				if (keys.length === 0) return;
+
+				try {
+					const results = await this.batchFn(keys);
+					keys.forEach((key, index) => {
+						const callbacks = batch.get(key)!;
+						const result = results[index] ?? null;
+						for (const { resolve } of callbacks) resolve(result);
+					});
+				} catch (error) {
+					for (const callbacks of batch.values()) {
+						for (const { reject } of callbacks) reject(error as Error);
+					}
+				}
+			}
+
+			clear(): void {
+				this.batch.clear();
+			}
+		}
+
+		const loader = new TestDataLoader(async (keys) => {
+			// Return null for some keys
+			return keys.map((k) => (k === "key2" ? null : `value-${k}`));
+		});
+
+		const results = await Promise.all([loader.load("key1"), loader.load("key2"), loader.load("key3")]);
+
+		expect(results).toEqual(["value-key1", null, "value-key3"]);
+	});
+});
+
+// =============================================================================
+// Test: HTTP Server Lifecycle (listen, close, findConnectionByWs)
+// =============================================================================
+
+describe("HTTP Server Lifecycle", () => {
+	it("handles GET requests that are not metadata endpoint", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const request = new Request("http://localhost/some-other-path", { method: "GET" });
+		const response = await server.handleRequest(request);
+
+		expect(response.status).toBe(405);
+		const text = await response.text();
+		expect(text).toBe("Method not allowed");
+	});
+
+	it("handles PUT requests", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const request = new Request("http://localhost/api", { method: "PUT" });
+		const response = await server.handleRequest(request);
+
+		expect(response.status).toBe(405);
+		const text = await response.text();
+		expect(text).toBe("Method not allowed");
+	});
+
+	it("handles DELETE requests", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const request = new Request("http://localhost/api", { method: "DELETE" });
+		const response = await server.handleRequest(request);
+
+		expect(response.status).toBe(405);
+		const text = await response.text();
+		expect(text).toBe("Method not allowed");
+	});
+
+	it("handles PATCH requests", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const request = new Request("http://localhost/api", { method: "PATCH" });
+		const response = await server.handleRequest(request);
+
+		expect(response.status).toBe(405);
+		const text = await response.text();
+		expect(text).toBe("Method not allowed");
+	});
+
+	it("handles OPTIONS requests", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const request = new Request("http://localhost/api", { method: "OPTIONS" });
+		const response = await server.handleRequest(request);
+
+		expect(response.status).toBe(405);
+		const text = await response.text();
+		expect(text).toBe("Method not allowed");
+	});
+
+	it("handles HEAD requests", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const request = new Request("http://localhost/api", { method: "HEAD" });
+		const response = await server.handleRequest(request);
+
+		expect(response.status).toBe(405);
+	});
+
+	it("can start and stop server with listen/close", async () => {
+		const server = createServer({
+			entities: { User },
+			logger: {
+				info: () => {}, // Silent logger for test
+			},
+		});
+
+		// Start server on a random high port to avoid conflicts
+		const port = 30000 + Math.floor(Math.random() * 10000);
+
+		try {
+			await server.listen(port);
+
+			// Verify server is running by making a request
+			const response = await fetch(`http://localhost:${port}/__lens/metadata`);
+			expect(response.status).toBe(200);
+			const data = await response.json();
+			expect(data.version).toBeDefined();
+		} finally {
+			// Always close the server
+			await server.close();
+		}
+	});
+
+	it("handles method not allowed via real HTTP server", async () => {
+		const server = createServer({
+			entities: { User },
+			logger: {
+				info: () => {}, // Silent logger for test
+			},
+		});
+
+		const port = 30000 + Math.floor(Math.random() * 10000);
+
+		try {
+			await server.listen(port);
+
+			// Make a PUT request which should return 405
+			const response = await fetch(`http://localhost:${port}/api`, { method: "PUT" });
+			expect(response.status).toBe(405);
+			const text = await response.text();
+			expect(text).toBe("Method not allowed");
+		} finally {
+			await server.close();
+		}
+	});
+
+	// Note: WebSocket integration via Bun.serve's native WebSocket upgrade (lines 1184-1193)
+	// is tested through unit tests using mock WebSockets. Full integration tests with real
+	// WebSocket clients would require additional setup and are better suited for E2E tests.
+});
+
+// =============================================================================
+// Test: SSE Handler Edge Cases
+// =============================================================================
+
+describe("SSE Handler Edge Cases", () => {
+	it("handles WebSocket error callback", async () => {
+		const server = createServer({
+			entities: { User },
+		});
+
+		const ws = createMockWs();
+		server.handleWebSocket(ws);
+
+		// Trigger error callback (if set)
+		if (ws.onerror) {
+			ws.onerror(new Error("WebSocket error"));
+		}
+
+		// Should not crash
+		expect(true).toBe(true);
+	});
+});
+
 // =============================================================================
 // Test: Entity Resolvers
 // =============================================================================

package/src/server/create.ts

@@ -18,12 +18,16 @@ import {
 	type FieldType,
 	flattenRouter,
 	type InferRouterContext,
+	isEntityDef,
 	isMutationDef,
+	isPipeline,
 	isQueryDef,
 	type MutationDef,
+	type Pipeline,
 	type QueryDef,
 	type ResolverDef,
 	type Resolvers,
+	type ReturnSpec,
 	type RouterDef,
 	runWithContext,
 	toResolverMap,
@@ -35,7 +39,7 @@ export interface SelectionObject {
 	[key: string]: boolean | SelectionObject | { select: SelectionObject };
 }
 
-import { GraphStateManager } from "../state/graph-state-manager";
+import { GraphStateManager } from "../state/graph-state-manager.js";
 
 // =============================================================================
 // Types
@@ -77,21 +81,21 @@ export interface LensServerConfig<
 	TRouter extends RouterDef = RouterDef,
 > {
 	/** Entity definitions */
-	entities?: EntitiesMap;
+	entities?: EntitiesMap | undefined;
 	/** Router definition (namespaced operations) - context type is inferred */
-	router?: TRouter;
+	router?: TRouter | undefined;
 	/** Query definitions (flat, legacy) */
-	queries?: QueriesMap;
+	queries?: QueriesMap | undefined;
 	/** Mutation definitions (flat, legacy) */
-	mutations?: MutationsMap;
+	mutations?: MutationsMap | undefined;
 	/** Field resolvers array (use lens() factory to create) */
-	resolvers?: Resolvers;
+	resolvers?: Resolvers | undefined;
 	/** Logger for server messages (default: silent) */
-	logger?: LensLogger;
+	logger?: LensLogger | undefined;
 	/** Context factory - must return the context type expected by the router */
-	context?: (req?: unknown) => TContext | Promise<TContext>;
+	context?: ((req?: unknown) => TContext | Promise<TContext>) | undefined;
 	/** Server version */
-	version?: string;
+	version?: string | undefined;
 }
 
 /** Server metadata for transport handshake */
@@ -149,6 +153,121 @@ export interface WebSocketLike {
 	onerror?: ((error: unknown) => void) | null;
 }
 
+// =============================================================================
+// Sugar to Reify Pipeline Conversion
+// =============================================================================
+
+/**
+ * Extract entity type name from return spec.
+ * Returns undefined if not an entity.
+ */
+function getEntityTypeName(returnSpec: ReturnSpec | undefined): string | undefined {
+	if (!returnSpec) return undefined;
+
+	// Single entity: EntityDef
+	if (isEntityDef(returnSpec)) {
+		return returnSpec._name;
+	}
+
+	// Array of entities: [EntityDef]
+	if (Array.isArray(returnSpec) && returnSpec.length === 1 && isEntityDef(returnSpec[0])) {
+		return returnSpec[0]._name;
+	}
+
+	return undefined;
+}
+
+/**
+ * Get input field keys from a Zod-like schema.
+ * Falls back to empty array if schema doesn't have shape.
+ */
+function getInputFields(inputSchema: { shape?: Record<string, unknown> } | undefined): string[] {
+	if (!inputSchema?.shape) return [];
+	return Object.keys(inputSchema.shape);
+}
+
+/**
+ * Convert sugar syntax to Reify Pipeline.
+ *
+ * Sugar syntax:
+ * - "merge" → entity.update with input fields merged
+ * - "create" → entity.create with temp ID
+ * - "delete" → entity.delete by input.id
+ * - { merge: {...} } → entity.update with input + extra fields
+ *
+ * Returns the original value if already a Pipeline or not sugar.
+ */
+function sugarToPipeline(
+	optimistic: unknown,
+	entityType: string | undefined,
+	inputFields: string[],
+): Pipeline | unknown {
+	// Already a Pipeline - pass through
+	if (isPipeline(optimistic)) {
+		return optimistic;
+	}
+
+	// No entity type - can't convert sugar
+	if (!entityType) {
+		return optimistic;
+	}
+
+	// "merge" sugar - update entity with input fields
+	if (optimistic === "merge") {
+		const args: Record<string, unknown> = { type: entityType };
+		for (const field of inputFields) {
+			args[field] = { $input: field };
+		}
+		return {
+			$pipe: [{ $do: "entity.update", $with: args }],
+		};
+	}
+
+	// "create" sugar - create entity with temp ID
+	if (optimistic === "create") {
+		const args: Record<string, unknown> = { type: entityType, id: { $temp: true } };
+		for (const field of inputFields) {
+			if (field !== "id") {
+				args[field] = { $input: field };
+			}
+		}
+		return {
+			$pipe: [{ $do: "entity.create", $with: args }],
+		};
+	}
+
+	// "delete" sugar - delete entity by input.id
+	if (optimistic === "delete") {
+		return {
+			$pipe: [{ $do: "entity.delete", $with: { type: entityType, id: { $input: "id" } } }],
+		};
+	}
+
+	// { merge: {...} } sugar - update with input + extra fields
+	if (
+		typeof optimistic === "object" &&
+		optimistic !== null &&
+		"merge" in optimistic &&
+		typeof (optimistic as Record<string, unknown>).merge === "object"
+	) {
+		const extra = (optimistic as { merge: Record<string, unknown> }).merge;
+		const args: Record<string, unknown> = { type: entityType };
+		for (const field of inputFields) {
+			args[field] = { $input: field };
+		}
+		// Extra fields override input refs
+		for (const [key, value] of Object.entries(extra)) {
+			args[key] = value;
+		}
+		return {
+			$pipe: [{ $do: "entity.update", $with: args }],
+		};
+	}
+
+	// Unknown format - pass through
+	return optimistic;
+}
+
 // =============================================================================
 // Protocol Messages
 // =============================================================================
@@ -309,7 +428,7 @@ class LensServerImpl<
 	private queries: Q;
 	private mutations: M;
 	private entities: EntitiesMap;
-	private resolverMap?: ResolverMap;
+	private resolverMap?: ResolverMap | undefined;
 	private contextFactory: (req?: unknown) => TContext | Promise<TContext>;
 	private version: string;
 	private logger: LensLogger;
@@ -479,11 +598,14 @@ class LensServerImpl<
 			setNested(name, { type: "query" });
 		}
 
-		// Add mutations with optimistic config
+		// Add mutations with optimistic config (convert sugar to Reify Pipeline)
 		for (const [name, def] of Object.entries(this.mutations)) {
 			const meta: OperationMeta = { type: "mutation" };
 			if (def._optimistic) {
-				meta.optimistic = def._optimistic;
+				// Convert sugar syntax to Reify Pipeline
+				const entityType = getEntityTypeName(def._output);
+				const inputFields = getInputFields(def._input as { shape?: Record<string, unknown> });
+				meta.optimistic = sugarToPipeline(def._optimistic, entityType, inputFields);
 			}
 			setNested(name, meta);
 		}
@@ -701,11 +823,16 @@ class LensServerImpl<
 				};
 			};
 
-			const result = resolver({
-				input: sub.input,
-				ctx: context,
+			// Merge Lens extensions (emit, onCleanup) into user context
+			const lensContext = {
+				...context,
 				emit,
 				onCleanup,
+			};
+
+			const result = resolver({
+				input: sub.input,
+				ctx: lensContext,
 			});
 
 			if (isAsyncIterable(result)) {
@@ -920,11 +1047,16 @@ class LensServerImpl<
 				const emit = createEmit(() => {});
 				const onCleanup = () => () => {};
 
-				const result = resolver({
-					input: cleanInput as TInput,
-					ctx: context,
+				// Merge Lens extensions (emit, onCleanup) into user context
+				const lensContext = {
+					...context,
 					emit,
 					onCleanup,
+				};
+
+				const result = resolver({
+					input: cleanInput as TInput,
+					ctx: lensContext,
 				});
 
 				let data: TOutput;
@@ -974,11 +1106,16 @@ class LensServerImpl<
 				const emit = createEmit(() => {});
 				const onCleanup = () => () => {};
 
-				const result = await resolver({
-					input: input as TInput,
-					ctx: context,
+				// Merge Lens extensions (emit, onCleanup) into user context
+				const lensContext = {
+					...context,
 					emit,
 					onCleanup,
+				};
+
+				const result = await resolver({
+					input: input as TInput,
+					ctx: lensContext,
 				});
 
 				// Emit to GraphStateManager

package/src/sse/handler.ts

@@ -5,7 +5,7 @@
  * Connects SSE streams to GraphStateManager.
  */
 
-import type { GraphStateManager, StateClient } from "../state/graph-state-manager";
+import type { GraphStateManager, StateClient } from "../state/graph-state-manager.js";
 
 // =============================================================================
 // Types

package/src/state/graph-state-manager.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { beforeEach, describe, expect, it, mock } from "bun:test";
-import { GraphStateManager, type StateClient, type StateUpdateMessage } from "./graph-state-manager";
+import { GraphStateManager, type StateClient, type StateUpdateMessage } from "./graph-state-manager.js";
 
 describe("GraphStateManager", () => {
 	let manager: GraphStateManager;

package/src/state/index.ts

@@ -13,4 +13,4 @@ export {
 	type StateFullMessage,
 	type StateUpdateMessage,
 	type Subscription,
-} from "./graph-state-manager";
+} from "./graph-state-manager.js";