@sylphx/lens-server 1.5.1 → 1.5.6

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);
     }
@@ -1141,7 +1209,7 @@ class LensServerImpl {
     const result = {};
     const obj = data;
     if ("id" in obj) {
-      result.id = obj.id;
+      result["id"] = obj["id"];
     }
     if (Array.isArray(fields)) {
       for (const field of fields) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/lens-server",
-	"version": "1.5.1",
+	"version": "1.5.6",
 	"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.10.0"
+		"@sylphx/lens-core": "^1.15.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.9.3",

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

@@ -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" },
+						},
+					},
+				],
+			},
 		});
 	});
 

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);
 		}
@@ -1178,7 +1300,7 @@ class LensServerImpl<
 
 		// Always include id
 		if ("id" in obj) {
-			result.id = obj.id;
+			result["id"] = obj["id"];
 		}
 
 		// Handle string array (simple field list)

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;
@@ -62,7 +62,7 @@ describe("GraphStateManager", () => {
 				entity: "Post",
 				id: "123",
 			});
-			expect(mockClient.messages[0].updates.title).toMatchObject({
+			expect(mockClient.messages[0].updates["title"]).toMatchObject({
 				strategy: "value",
 				data: "Hello",
 			});
@@ -179,7 +179,7 @@ describe("GraphStateManager", () => {
 
 			manager.emit("Post", "123", { title: "World" });
 
-			expect(mockClient.messages[0].updates.title.strategy).toBe("value");
+			expect(mockClient.messages[0].updates["title"].strategy).toBe("value");
 		});
 
 		it("uses delta strategy for long strings with small changes", () => {
@@ -191,7 +191,7 @@ describe("GraphStateManager", () => {
 			manager.emit("Post", "123", { content: `${longText} appended` });
 
 			// Should use delta for efficient transfer
-			const update = mockClient.messages[0].updates.content;
+			const update = mockClient.messages[0].updates["content"];
 			expect(["delta", "value"]).toContain(update.strategy);
 		});
 
@@ -206,7 +206,7 @@ describe("GraphStateManager", () => {
 				metadata: { views: 101, likes: 10, tags: ["a", "b"] },
 			});
 
-			const update = mockClient.messages[0].updates.metadata;
+			const update = mockClient.messages[0].updates["metadata"];
 			expect(["patch", "value"]).toContain(update.strategy);
 		});
 	});
@@ -258,12 +258,12 @@ describe("GraphStateManager", () => {
 
 			// client-1 got incremental update
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.title.data).toBe("Updated");
+			expect(mockClient.messages[0].updates["title"].data).toBe("Updated");
 
 			// client-2 got full current state
 			expect(client2.messages.length).toBe(1);
-			expect(client2.messages[0].updates.title.data).toBe("Updated");
-			expect(client2.messages[0].updates.content.data).toBe("World");
+			expect(client2.messages[0].updates["title"].data).toBe("Updated");
+			expect(client2.messages[0].updates["content"].data).toBe("World");
 		});
 	});
 
@@ -390,7 +390,7 @@ describe("GraphStateManager", () => {
 			manager.emitField("Post", "123", "title", { strategy: "value", data: "Hello World" });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.title).toEqual({
+			expect(mockClient.messages[0].updates["title"]).toEqual({
 				strategy: "value",
 				data: "Hello World",
 			});
@@ -424,7 +424,7 @@ describe("GraphStateManager", () => {
 			});
 
 			const state = manager.getState("Post", "123");
-			expect(state?.metadata).toEqual({ views: 101, likes: 10 });
+			expect(state?.["metadata"]).toEqual({ views: 101, likes: 10 });
 		});
 
 		it("sends field update to subscribed clients only for subscribed fields", () => {
@@ -480,9 +480,9 @@ describe("GraphStateManager", () => {
 			]);
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.title.data).toBe("Hello");
-			expect(mockClient.messages[0].updates.content.data).toBe("World");
-			expect(mockClient.messages[0].updates.author.data).toBe("Alice");
+			expect(mockClient.messages[0].updates["title"].data).toBe("Hello");
+			expect(mockClient.messages[0].updates["content"].data).toBe("World");
+			expect(mockClient.messages[0].updates["author"].data).toBe("Alice");
 		});
 
 		it("applies batch updates to canonical state", () => {
@@ -712,7 +712,7 @@ describe("GraphStateManager", () => {
 			});
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.author.data).toEqual({
+			expect(mockClient.messages[0].updates["author"].data).toEqual({
 				id: "1",
 				name: "Alice",
 				profile: {
@@ -792,7 +792,7 @@ describe("GraphStateManager", () => {
 
 			// Should have 10 updates
 			expect(mockClient.messages.length).toBe(10);
-			expect(mockClient.messages[9].updates.counter.data).toBe(9);
+			expect(mockClient.messages[9].updates["counter"].data).toBe(9);
 		});
 
 		it("handles large number of subscribers to same entity", () => {
@@ -815,7 +815,7 @@ describe("GraphStateManager", () => {
 			// All clients should receive the update
 			for (const client of clients) {
 				expect(client.messages.length).toBe(1);
-				expect(client.messages[0].updates.title.data).toBe("Broadcast");
+				expect(client.messages[0].updates["title"].data).toBe("Broadcast");
 			}
 		});
 
@@ -842,14 +842,14 @@ describe("GraphStateManager", () => {
 			manager.emit("Post", "123", { tags: ["javascript", "typescript"] });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.tags.data).toEqual(["javascript", "typescript"]);
+			expect(mockClient.messages[0].updates["tags"].data).toEqual(["javascript", "typescript"]);
 
 			// Update array
 			mockClient.messages = [];
 			manager.emit("Post", "123", { tags: ["javascript", "typescript", "react"] });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.tags.data).toEqual(["javascript", "typescript", "react"]);
+			expect(mockClient.messages[0].updates["tags"].data).toEqual(["javascript", "typescript", "react"]);
 		});
 
 		it("handles boolean field values", () => {
@@ -859,14 +859,14 @@ describe("GraphStateManager", () => {
 			manager.emit("Post", "123", { published: true });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.published.data).toBe(true);
+			expect(mockClient.messages[0].updates["published"].data).toBe(true);
 
 			// Toggle boolean
 			mockClient.messages = [];
 			manager.emit("Post", "123", { published: false });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.published.data).toBe(false);
+			expect(mockClient.messages[0].updates["published"].data).toBe(false);
 		});
 
 		it("handles number field values including 0", () => {
@@ -876,14 +876,14 @@ describe("GraphStateManager", () => {
 			manager.emit("Post", "123", { likes: 0 });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.likes.data).toBe(0);
+			expect(mockClient.messages[0].updates["likes"].data).toBe(0);
 
 			// Update to positive number
 			mockClient.messages = [];
 			manager.emit("Post", "123", { likes: 5 });
 
 			expect(mockClient.messages.length).toBe(1);
-			expect(mockClient.messages[0].updates.likes.data).toBe(5);
+			expect(mockClient.messages[0].updates["likes"].data).toBe(5);
 		});
 	});
 
@@ -909,7 +909,7 @@ describe("GraphStateManager", () => {
 				entity: "Users",
 				id: "list",
 			});
-			expect(mockClient.messages[0].updates._items.data).toEqual([
+			expect(mockClient.messages[0].updates["_items"].data).toEqual([
 				{ id: "1", name: "Alice" },
 				{ id: "2", name: "Bob" },
 			]);
@@ -1086,7 +1086,7 @@ describe("GraphStateManager", () => {
 
 			expect(mockClient.messages.length).toBe(2);
 			// Second message should be incremental diff (push operation)
-			const update = mockClient.messages[1].updates._items;
+			const update = mockClient.messages[1].updates["_items"];
 			expect(update.strategy).toBe("array");
 			expect(update.data).toEqual([{ op: "push", item: { id: "2", name: "Bob" } }]);
 		});

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";