@sylphx/lens-server 1.0.4 → 1.3.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { ContextValue, EntityDef, EntityDefinition, EntityResolvers, EntityResolversDefinition, MutationDef, QueryDef, RelationDef, RelationTypeWithForeignKey, RouterDef } from "@sylphx/lens-core";
-import { EntityKey, Update } from "@sylphx/lens-core";
+import { query, mutation, router, QueryBuilder, MutationBuilder, QueryDef as QueryDef2, MutationDef as MutationDef2, RouterDef as RouterDef2, RouterRoutes, ResolverFn, ResolverContext, InferRouterContext as InferRouterContext2 } from "@sylphx/lens-core";
+import { ContextValue, EntityDef, EntityDefinition, EntityResolvers, EntityResolversDefinition, InferRouterContext, MutationDef, QueryDef, RelationDef, RelationTypeWithForeignKey, RouterDef } from "@sylphx/lens-core";
+import { EntityKey, Update, EmitCommand, InternalFieldUpdate, ArrayOperation } from "@sylphx/lens-core";
 /** Client connection interface */
 interface StateClient {
 	id: string;
@@ -56,8 +57,12 @@ declare class GraphStateManager {
 	private clients;
 	/** Canonical state per entity (server truth) */
 	private canonical;
+	/** Canonical array state per entity (server truth for array outputs) */
+	private canonicalArrays;
 	/** Per-client state tracking */
 	private clientStates;
+	/** Per-client array state tracking */
+	private clientArrayStates;
 	/** Entity → subscribed client IDs */
 	private entitySubscribers;
 	/** Configuration */
@@ -96,6 +101,63 @@ declare class GraphStateManager {
 		replace?: boolean;
 	}): void;
 	/**
+	* Emit a field-level update with a specific strategy.
+	* Applies the update to canonical state and pushes to clients.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param field - Field name to update
+	* @param update - Update with strategy (value/delta/patch)
+	*/
+	emitField(entity: string, id: string, field: string, update: Update): void;
+	/**
+	* Emit multiple field updates in a batch.
+	* More efficient than multiple emitField calls.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param updates - Array of field updates
+	*/
+	emitBatch(entity: string, id: string, updates: InternalFieldUpdate[]): void;
+	/**
+	* Process an EmitCommand from the Emit API.
+	* Routes to appropriate emit method.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param command - Emit command from resolver
+	*/
+	processCommand(entity: string, id: string, command: EmitCommand): void;
+	/**
+	* Emit array data (replace entire array).
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param items - Array items
+	*/
+	emitArray(entity: string, id: string, items: unknown[]): void;
+	/**
+	* Apply an array operation to the canonical state.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param operation - Array operation to apply
+	*/
+	emitArrayOperation(entity: string, id: string, operation: ArrayOperation): void;
+	/**
+	* Apply an array operation and return new array.
+	*/
+	private applyArrayOperation;
+	/**
+	* Push array update to a specific client.
+	* Computes optimal diff strategy.
+	*/
+	private pushArrayToClient;
+	/**
+	* Get current canonical array state
+	*/
+	getArrayState(entity: string, id: string): unknown[] | undefined;
+	/**
 	* Get current canonical state for an entity
 	*/
 	getState(entity: string, id: string): Record<string, unknown> | undefined;
@@ -108,6 +170,16 @@ declare class GraphStateManager {
 	*/
 	private pushToClient;
 	/**
+	* Push a single field update to a client.
+	* Computes optimal transfer strategy.
+	*/
+	private pushFieldToClient;
+	/**
+	* Push multiple field updates to a client.
+	* Computes optimal transfer strategy for each field.
+	*/
+	private pushFieldsToClient;
+	/**
 	* Send initial data to a newly subscribed client
 	*/
 	private sendInitialData;
@@ -157,20 +229,23 @@ type OperationsMap = {
 	[key: string]: OperationMeta | OperationsMap;
 };
 /** Server configuration */
-interface LensServerConfig<TContext extends ContextValue = ContextValue> {
+interface LensServerConfig<
+	TContext extends ContextValue = ContextValue,
+	TRouter extends RouterDef = RouterDef
+> {
 	/** Entity definitions */
 	entities?: EntitiesMap;
 	/** Relation definitions */
 	relations?: RelationsArray;
-	/** Router definition (namespaced operations) */
-	router?: RouterDef;
+	/** Router definition (namespaced operations) - context type is inferred */
+	router?: TRouter;
 	/** Query definitions (flat, legacy) */
 	queries?: QueriesMap;
 	/** Mutation definitions (flat, legacy) */
 	mutations?: MutationsMap;
 	/** Entity resolvers */
 	resolvers?: EntityResolvers<EntityResolversDefinition>;
-	/** Context factory */
+	/** Context factory - must return the context type expected by the router */
 	context?: (req?: unknown) => TContext | Promise<TContext>;
 	/** Server version */
 	version?: string;
@@ -351,19 +426,78 @@ type InferApi<T extends LensServer> = T extends LensServerImpl<infer Q, infer M>
 	mutations: M;
 } : never;
 /**
-* Create Lens server with Operations API + Optimization Layer
+* Config helper type that infers context from router
 */
-declare function createServer<
+type ServerConfigWithInferredContext<
+	TRouter extends RouterDef,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap
+> = {
+	entities?: EntitiesMap;
+	relations?: RelationsArray;
+	router: TRouter;
+	queries?: Q;
+	mutations?: M;
+	resolvers?: EntityResolvers<EntityResolversDefinition>;
+	/** Context factory - type is inferred from router's procedures */
+	context?: (req?: unknown) => InferRouterContext<TRouter> | Promise<InferRouterContext<TRouter>>;
+	version?: string;
+};
+/**
+* Config without router (legacy flat queries/mutations)
+*/
+type ServerConfigLegacy<
 	TContext extends ContextValue = ContextValue,
 	Q extends QueriesMap = QueriesMap,
 	M extends MutationsMap = MutationsMap
->(config: LensServerConfig<TContext> & {
+> = {
+	entities?: EntitiesMap;
+	relations?: RelationsArray;
+	router?: undefined;
 	queries?: Q;
 	mutations?: M;
-}): LensServer & {
+	resolvers?: EntityResolvers<EntityResolversDefinition>;
+	context?: (req?: unknown) => TContext | Promise<TContext>;
+	version?: string;
+};
+/**
+* Create Lens server with Operations API + Optimization Layer
+*
+* When using a router with typed context (from initLens), the context
+* function's return type is automatically enforced to match.
+*
+* @example
+* ```typescript
+* // Context type is inferred from router's procedures
+* const server = createServer({
+*   router: appRouter,  // RouterDef with MyContext
+*   context: () => ({
+*     db: prisma,
+*     user: null,
+*   }),  // Must match MyContext!
+* })
+* ```
+*/
+declare function createServer<
+	TRouter extends RouterDef,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap
+>(config: ServerConfigWithInferredContext<TRouter, Q, M>): LensServer & {
+	_types: {
+		queries: Q;
+		mutations: M;
+		context: InferRouterContext<TRouter>;
+	};
+};
+declare function createServer<
+	TContext extends ContextValue = ContextValue,
+	Q extends QueriesMap = QueriesMap,
+	M extends MutationsMap = MutationsMap
+>(config: ServerConfigLegacy<TContext, Q, M>): LensServer & {
 	_types: {
 		queries: Q;
 		mutations: M;
+		context: TContext;
 	};
 };
 /** SSE handler configuration */
@@ -436,4 +570,4 @@ declare class SSEHandler {
 * Create SSE handler (transport adapter)
 */
 declare function createSSEHandler(config: SSEHandlerConfig): SSEHandler;
-export { createServer, createSSEHandler, createGraphStateManager, WebSocketLike, Subscription, StateUpdateMessage, StateFullMessage, StateClient, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig, SSEHandler, SSEClientInfo, RelationsArray, QueriesMap, OperationsMap, OperationMeta, MutationsMap, LensServer, LensResult, LensOperation, InferOutput, InferInput, InferApi, GraphStateManagerConfig, GraphStateManager, EntityKey, EntitiesMap };
+export { router, query, mutation, createServer, createSSEHandler, createGraphStateManager, WebSocketLike, Subscription, StateUpdateMessage, StateFullMessage, StateClient, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig, SSEHandler, SSEClientInfo, RouterRoutes, RouterDef2 as RouterDef, ResolverFn, ResolverContext, RelationsArray, QueryDef2 as QueryDef, QueryBuilder, QueriesMap, OperationsMap, OperationMeta, MutationsMap, MutationDef2 as MutationDef, MutationBuilder, LensServer, LensResult, LensOperation, InferRouterContext2 as InferRouterContext, InferOutput, InferInput, InferApi, GraphStateManagerConfig, GraphStateManager, EntityKey, EntitiesMap };

package/dist/index.js

@@ -1,6 +1,14 @@
+// src/index.ts
+import {
+  query,
+  mutation,
+  router
+} from "@sylphx/lens-core";
+
 // src/server/create.ts
 import {
   createContext,
+  createEmit,
   createUpdate as createUpdate2,
   flattenRouter,
   isBatchResolver,
@@ -10,12 +18,18 @@ import {
 } from "@sylphx/lens-core";
 
 // src/state/graph-state-manager.ts
-import { createUpdate, makeEntityKey } from "@sylphx/lens-core";
+import {
+  createUpdate,
+  applyUpdate,
+  makeEntityKey
+} from "@sylphx/lens-core";
 
 class GraphStateManager {
   clients = new Map;
   canonical = new Map;
+  canonicalArrays = new Map;
   clientStates = new Map;
+  clientArrayStates = new Map;
   entitySubscribers = new Map;
   config;
   constructor(config = {}) {
@@ -24,6 +38,7 @@ class GraphStateManager {
   addClient(client) {
     this.clients.set(client.id, client);
     this.clientStates.set(client.id, new Map);
+    this.clientArrayStates.set(client.id, new Map);
   }
   removeClient(clientId) {
     for (const [key, subscribers] of this.entitySubscribers) {
@@ -34,6 +49,7 @@ class GraphStateManager {
     }
     this.clients.delete(clientId);
     this.clientStates.delete(clientId);
+    this.clientArrayStates.delete(clientId);
   }
   subscribe(clientId, entity, id, fields = "*") {
     const key = this.makeKey(entity, id);
@@ -96,6 +112,148 @@ class GraphStateManager {
       this.pushToClient(clientId, entity, id, key, currentCanonical);
     }
   }
+  emitField(entity, id, field, update) {
+    const key = this.makeKey(entity, id);
+    let currentCanonical = this.canonical.get(key);
+    if (!currentCanonical) {
+      currentCanonical = {};
+    }
+    const oldValue = currentCanonical[field];
+    const newValue = applyUpdate(oldValue, update);
+    currentCanonical = { ...currentCanonical, [field]: newValue };
+    this.canonical.set(key, currentCanonical);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushFieldToClient(clientId, entity, id, key, field, newValue);
+    }
+  }
+  emitBatch(entity, id, updates) {
+    const key = this.makeKey(entity, id);
+    let currentCanonical = this.canonical.get(key);
+    if (!currentCanonical) {
+      currentCanonical = {};
+    }
+    const changedFields = [];
+    for (const { field, update } of updates) {
+      const oldValue = currentCanonical[field];
+      const newValue = applyUpdate(oldValue, update);
+      currentCanonical[field] = newValue;
+      changedFields.push(field);
+    }
+    this.canonical.set(key, currentCanonical);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushFieldsToClient(clientId, entity, id, key, changedFields, currentCanonical);
+    }
+  }
+  processCommand(entity, id, command) {
+    switch (command.type) {
+      case "full":
+        this.emit(entity, id, command.data, {
+          replace: command.replace
+        });
+        break;
+      case "field":
+        this.emitField(entity, id, command.field, command.update);
+        break;
+      case "batch":
+        this.emitBatch(entity, id, command.updates);
+        break;
+      case "array":
+        this.emitArrayOperation(entity, id, command.operation);
+        break;
+    }
+  }
+  emitArray(entity, id, items) {
+    const key = this.makeKey(entity, id);
+    this.canonicalArrays.set(key, [...items]);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushArrayToClient(clientId, entity, id, key, items);
+    }
+  }
+  emitArrayOperation(entity, id, operation) {
+    const key = this.makeKey(entity, id);
+    let currentArray = this.canonicalArrays.get(key);
+    if (!currentArray) {
+      currentArray = [];
+    }
+    const newArray = this.applyArrayOperation([...currentArray], operation);
+    this.canonicalArrays.set(key, newArray);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushArrayToClient(clientId, entity, id, key, newArray);
+    }
+  }
+  applyArrayOperation(array, operation) {
+    switch (operation.op) {
+      case "push":
+        return [...array, operation.item];
+      case "unshift":
+        return [operation.item, ...array];
+      case "insert":
+        return [
+          ...array.slice(0, operation.index),
+          operation.item,
+          ...array.slice(operation.index)
+        ];
+      case "remove":
+        return [...array.slice(0, operation.index), ...array.slice(operation.index + 1)];
+      case "removeById": {
+        const idx = array.findIndex((item) => typeof item === "object" && item !== null && ("id" in item) && item.id === operation.id);
+        if (idx === -1)
+          return array;
+        return [...array.slice(0, idx), ...array.slice(idx + 1)];
+      }
+      case "update":
+        return array.map((item, i) => i === operation.index ? operation.item : item);
+      case "updateById":
+        return array.map((item) => typeof item === "object" && item !== null && ("id" in item) && item.id === operation.id ? operation.item : item);
+      case "merge":
+        return array.map((item, i) => i === operation.index && typeof item === "object" && item !== null ? { ...item, ...operation.partial } : item);
+      case "mergeById":
+        return array.map((item) => typeof item === "object" && item !== null && ("id" in item) && item.id === operation.id ? { ...item, ...operation.partial } : item);
+      default:
+        return array;
+    }
+  }
+  pushArrayToClient(clientId, entity, id, key, newArray) {
+    const client = this.clients.get(clientId);
+    if (!client)
+      return;
+    const clientArrayStateMap = this.clientArrayStates.get(clientId);
+    if (!clientArrayStateMap)
+      return;
+    let clientArrayState = clientArrayStateMap.get(key);
+    if (!clientArrayState) {
+      clientArrayState = { lastState: [] };
+      clientArrayStateMap.set(key, clientArrayState);
+    }
+    const { lastState } = clientArrayState;
+    if (JSON.stringify(lastState) === JSON.stringify(newArray)) {
+      return;
+    }
+    client.send({
+      type: "update",
+      entity,
+      id,
+      updates: {
+        _items: { strategy: "value", data: newArray }
+      }
+    });
+    clientArrayState.lastState = [...newArray];
+  }
+  getArrayState(entity, id) {
+    return this.canonicalArrays.get(this.makeKey(entity, id));
+  }
   getState(entity, id) {
     return this.canonical.get(this.makeKey(entity, id));
   }
@@ -143,6 +301,77 @@ class GraphStateManager {
       }
     }
   }
+  pushFieldToClient(clientId, entity, id, key, field, newValue) {
+    const client = this.clients.get(clientId);
+    if (!client)
+      return;
+    const clientStateMap = this.clientStates.get(clientId);
+    if (!clientStateMap)
+      return;
+    const clientEntityState = clientStateMap.get(key);
+    if (!clientEntityState)
+      return;
+    const { lastState, fields } = clientEntityState;
+    if (fields !== "*" && !fields.has(field)) {
+      return;
+    }
+    const oldValue = lastState[field];
+    if (oldValue === newValue)
+      return;
+    if (typeof oldValue === "object" && typeof newValue === "object" && JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+      return;
+    }
+    const update = createUpdate(oldValue, newValue);
+    client.send({
+      type: "update",
+      entity,
+      id,
+      updates: { [field]: update }
+    });
+    clientEntityState.lastState[field] = newValue;
+  }
+  pushFieldsToClient(clientId, entity, id, key, changedFields, newState) {
+    const client = this.clients.get(clientId);
+    if (!client)
+      return;
+    const clientStateMap = this.clientStates.get(clientId);
+    if (!clientStateMap)
+      return;
+    const clientEntityState = clientStateMap.get(key);
+    if (!clientEntityState)
+      return;
+    const { lastState, fields } = clientEntityState;
+    const updates = {};
+    let hasChanges = false;
+    for (const field of changedFields) {
+      if (fields !== "*" && !fields.has(field)) {
+        continue;
+      }
+      const oldValue = lastState[field];
+      const newValue = newState[field];
+      if (oldValue === newValue)
+        continue;
+      if (typeof oldValue === "object" && typeof newValue === "object" && JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+        continue;
+      }
+      const update = createUpdate(oldValue, newValue);
+      updates[field] = update;
+      hasChanges = true;
+    }
+    if (!hasChanges)
+      return;
+    client.send({
+      type: "update",
+      entity,
+      id,
+      updates
+    });
+    for (const field of changedFields) {
+      if (newState[field] !== undefined) {
+        clientEntityState.lastState[field] = newState[field];
+      }
+    }
+  }
   sendInitialData(clientId, entity, id, state, fields) {
     const client = this.clients.get(clientId);
     if (!client)
@@ -195,7 +424,9 @@ class GraphStateManager {
   clear() {
     this.clients.clear();
     this.canonical.clear();
+    this.canonicalArrays.clear();
     this.clientStates.clear();
+    this.clientArrayStates.clear();
     this.entitySubscribers.clear();
   }
 }
@@ -505,21 +736,31 @@ class LensServerImpl {
       if (!resolver) {
         throw new Error(`Query ${sub.operation} has no resolver`);
       }
-      const contextWithHelpers = {
-        ...context,
-        emit: emitData,
-        onCleanup: (fn) => {
-          sub.cleanups.push(fn);
-          return () => {
-            const idx = sub.cleanups.indexOf(fn);
-            if (idx >= 0)
-              sub.cleanups.splice(idx, 1);
-          };
+      const emit = createEmit((command) => {
+        const entityName = this.getEntityNameFromOutput(queryDef._output);
+        if (entityName) {
+          const entities = this.extractEntities(entityName, command.type === "full" ? command.data : {});
+          for (const { entity, id } of entities) {
+            this.stateManager.processCommand(entity, id, command);
+          }
         }
+        if (command.type === "full") {
+          emitData(command.data);
+        }
+      });
+      const onCleanup = (fn) => {
+        sub.cleanups.push(fn);
+        return () => {
+          const idx = sub.cleanups.indexOf(fn);
+          if (idx >= 0)
+            sub.cleanups.splice(idx, 1);
+        };
       };
       const result = resolver({
         input: sub.input,
-        ctx: contextWithHelpers
+        ctx: context,
+        emit,
+        onCleanup
       });
       if (isAsyncIterable(result)) {
         for await (const value of result) {
@@ -668,13 +909,14 @@ class LensServerImpl {
         if (!resolver) {
           throw new Error(`Query ${name} has no resolver`);
         }
-        const resolverCtx = {
+        const emit = createEmit(() => {});
+        const onCleanup = () => () => {};
+        const result = resolver({
           input: cleanInput,
           ctx: context,
-          emit: () => {},
-          onCleanup: () => () => {}
-        };
-        const result = resolver(resolverCtx);
+          emit,
+          onCleanup
+        });
         let data;
         if (isAsyncIterable(result)) {
           for await (const value of result) {
@@ -711,9 +953,13 @@ class LensServerImpl {
         if (!resolver) {
           throw new Error(`Mutation ${name} has no resolver`);
         }
+        const emit = createEmit(() => {});
+        const onCleanup = () => () => {};
         const result = await resolver({
           input,
-          ctx: context
+          ctx: context,
+          emit,
+          onCleanup
         });
         const entityName = this.getEntityNameFromMutation(name);
         const entities = this.extractEntities(entityName, result);
@@ -1164,6 +1410,9 @@ function createSSEHandler(config) {
   return new SSEHandler(config);
 }
 export {
+  router,
+  query,
+  mutation,
   createServer,
   createSSEHandler,
   createGraphStateManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylphx/lens-server",
-  "version": "1.0.4",
+  "version": "1.3.0",
   "description": "Server runtime for Lens API framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
   "author": "SylphxAI",
   "license": "MIT",
   "dependencies": {
-    "@sylphx/lens-core": "^1.0.4"
+    "@sylphx/lens-core": "^1.3.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

package/src/e2e/server.test.ts

@@ -306,14 +306,14 @@ describe("E2E - Subscriptions", () => {
 		expect(received[0]).toMatchObject({ name: "Alice" });
 	});
 
-	it("subscribe receives updates via ctx.emit", async () => {
+	it("subscribe receives updates via emit", async () => {
 		let emitFn: ((data: unknown) => void) | null = null;
 
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ input, emit }) => {
+				emitFn = emit;
 				return mockUsers.find((u) => u.id === input.id) ?? null;
 			});
 
@@ -355,8 +355,8 @@ describe("E2E - Subscriptions", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ input, emit }) => {
+				emitFn = emit;
 				return mockUsers.find((u) => u.id === input.id) ?? null;
 			});
 
@@ -447,7 +447,7 @@ describe("E2E - Server API", () => {
 });
 
 // =============================================================================
-// Test: Cleanup (ctx.onCleanup)
+// Test: Cleanup (onCleanup)
 // =============================================================================
 
 describe("E2E - Cleanup", () => {
@@ -457,8 +457,8 @@ describe("E2E - Cleanup", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				ctx.onCleanup(() => {
+			.resolve(({ input, onCleanup }) => {
+				onCleanup(() => {
 					cleanedUp = true;
 				});
 				return mockUsers.find((u) => u.id === input.id) ?? null;
@@ -497,8 +497,8 @@ describe("E2E - GraphStateManager", () => {
 		const getUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ input, emit }) => {
+				emitFn = emit;
 				return mockUsers.find((u) => u.id === input.id) ?? null;
 			});
 

package/src/index.ts

@@ -5,6 +5,27 @@
  * Operations-based server with GraphStateManager for reactive updates.
  */
 
+// =============================================================================
+// Re-exports from Core (commonly used with server)
+// =============================================================================
+
+export {
+	// Operations
+	query,
+	mutation,
+	router,
+	// Types
+	type QueryBuilder,
+	type MutationBuilder,
+	type QueryDef,
+	type MutationDef,
+	type RouterDef,
+	type RouterRoutes,
+	type ResolverFn,
+	type ResolverContext,
+	type InferRouterContext,
+} from "@sylphx/lens-core";
+
 // =============================================================================
 // Server
 // =============================================================================