@sylphx/lens-server 2.8.1 → 2.10.0

package/README.md

@@ -10,20 +10,217 @@ bun add @sylphx/lens-server
 
 ## Usage
 
+### Basic Server Setup
+
+```typescript
+import { createApp, createHandler } from "@sylphx/lens-server";
+import { model, lens, router, list, nullable } from "@sylphx/lens-core";
+import { z } from "zod";
+
+// Define context type
+interface AppContext {
+  db: Database;
+  user: User | null;
+}
+
+// Define models with inline resolvers
+const User = model<AppContext>("User", (t) => ({
+  id: t.id(),
+  name: t.string(),
+  email: t.string(),
+  posts: t.many(() => Post).resolve(({ parent, ctx }) =>
+    ctx.db.posts.filter(p => p.authorId === parent.id)
+  ),
+}));
+
+const Post = model<AppContext>("Post", (t) => ({
+  id: t.id(),
+  title: t.string(),
+  authorId: t.string(),
+}));
+
+// Create typed builders
+const { query, mutation } = lens<AppContext>();
+
+// Define operations
+const appRouter = router({
+  user: {
+    get: query()
+      .input(z.object({ id: z.string() }))
+      .returns(User)
+      .resolve(({ input, ctx }) => ctx.db.users.get(input.id)!),
+
+    find: query()
+      .input(z.object({ email: z.string() }))
+      .returns(nullable(User))  // User | null
+      .resolve(({ input, ctx }) => ctx.db.users.findByEmail(input.email)),
+
+    list: query()
+      .returns(list(User))  // User[]
+      .resolve(({ ctx }) => ctx.db.users.findMany()),
+
+    update: mutation()
+      .input(z.object({ id: z.string(), name: z.string() }))
+      .returns(User)
+      .resolve(({ input, ctx }) => ctx.db.users.update(input)),
+  },
+});
+
+// Create server - models auto-tracked from router!
+const app = createApp({
+  router: appRouter,  // Models extracted from .returns()
+  context: () => ({
+    db: database,
+    user: getCurrentUser(),
+  }),
+});
+
+// Start server
+const handler = createHandler(app);
+Bun.serve({ port: 3000, fetch: handler });
+```
+
+### With Optimistic Updates
+
 ```typescript
-import { createServer } from "@sylphx/lens-server";
-import { appRouter } from "./router";
+import { createApp, optimisticPlugin } from "@sylphx/lens-server";
+import { model, lens, router } from "@sylphx/lens-core";
+import { entity as e, temp, now } from "@sylphx/reify";
 
-const server = createServer({ router: appRouter });
+// Enable optimistic plugin
+const { query, mutation, plugins } = lens<AppContext>()
+  .withPlugins([optimisticPlugin()]);
+
+const appRouter = router({
+  user: {
+    // Sugar syntax
+    update: mutation()
+      .input(z.object({ id: z.string(), name: z.string() }))
+      .returns(User)
+      .optimistic("merge")  // Instant UI update
+      .resolve(({ input, ctx }) => ctx.db.users.update(input)),
+  },
+  message: {
+    // Reify DSL (multi-entity)
+    send: mutation()
+      .input(z.object({ content: z.string(), userId: z.string() }))
+      .returns(Message)
+      .optimistic(({ input }) => [
+        e.create(Message, {
+          id: temp(),
+          content: input.content,
+          createdAt: now(),
+        }),
+      ])
+      .resolve(({ input, ctx }) => ctx.db.messages.create(input)),
+  },
+});
+
+const app = createApp({
+  router: appRouter,
+  plugins,  // Include optimistic plugin
+  context: () => ({ ... }),
+});
+```
+
+### Live Queries
+
+```typescript
+const { query } = lens<AppContext>();
+
+// Live query with Publisher pattern
+const watchUser = query()
+  .input(z.object({ id: z.string() }))
+  .resolve(({ input, ctx }) => ctx.db.users.get(input.id)!)  // Initial value
+  .subscribe(({ input, ctx }) => ({ emit, onCleanup }) => {
+    // Publisher callback - emit/onCleanup passed here
+    const unsub = ctx.db.users.onChange(input.id, (user) => {
+      emit(user);  // Push update to clients
+    });
+    onCleanup(unsub);  // Cleanup on disconnect
+  });
+```
+
+### WebSocket Handler
+
+```typescript
+import { createApp, createHandler, createWSHandler } from "@sylphx/lens-server";
+
+const app = createApp({ ... });
+
+// HTTP handler
+const httpHandler = createHandler(app);
+
+// WebSocket handler
+const wsHandler = createWSHandler(app);
 
-// Handle WebSocket connections
 Bun.serve({
   port: 3000,
-  fetch: server.fetch,
-  websocket: server.websocket,
+  fetch(req, server) {
+    if (req.headers.get("upgrade") === "websocket") {
+      return wsHandler.upgrade(req, server);
+    }
+    return httpHandler(req);
+  },
+  websocket: wsHandler.websocket,
+});
+```
+
+## createApp Options
+
+```typescript
+createApp({
+  // Required (at least one)
+  router: RouterDef,           // Namespaced operations
+
+  // Optional (models auto-tracked from router!)
+  entities: EntitiesMap,       // Explicit models (optional, for overrides)
+  plugins: ServerPlugin[],     // Server plugins (optimistic, clientState, etc.)
+  context: () => TContext,     // Context factory
+  logger: LensLogger,          // Logging (default: silent)
+  version: string,             // Server version (default: "1.0.0")
 });
 ```
 
+## Auto-tracking Models
+
+Models are automatically collected from router return types:
+
+```typescript
+// These models are auto-tracked:
+const appRouter = router({
+  user: {
+    get: query().returns(User).resolve(...),     // User tracked
+    list: query().returns(list(User)).resolve(...), // User tracked
+    find: query().returns(nullable(User)).resolve(...), // User tracked
+  },
+  post: {
+    get: query().returns(Post).resolve(...),     // Post tracked
+  },
+});
+
+// No need to pass entities explicitly
+const app = createApp({
+  router: appRouter,  // User and Post auto-collected
+});
+
+// Or override/add explicit models
+const app = createApp({
+  router: appRouter,
+  entities: { User, Post, ExtraModel },  // Explicit takes priority
+});
+```
+
+## Optimistic Update Strategies
+
+| Strategy | Description | Example |
+|----------|-------------|---------|
+| `"merge"` | Merge input into entity | `.optimistic("merge")` |
+| `"create"` | Create with temp ID | `.optimistic("create")` |
+| `"delete"` | Mark entity deleted | `.optimistic("delete")` |
+| `{ merge: {...} }` | Merge with extra fields | `.optimistic({ merge: { status: "pending" } })` |
+| Reify DSL | Multi-entity operations | `.optimistic(({ input }) => [...])` |
+
 ## License
 
 MIT
@@ -32,4 +229,4 @@ MIT
 
 Built with [@sylphx/lens-core](https://github.com/SylphxAI/Lens).
 
-✨ Powered by Sylphx
+Powered by Sylphx

package/dist/index.d.ts

@@ -41,7 +41,7 @@ declare function extendContext<
 	E extends ContextValue
 >(current: T, extension: E): T & E;
 import { ContextValue as ContextValue3, InferRouterContext as InferRouterContext2, RouterDef as RouterDef2 } from "@sylphx/lens-core";
-import { ContextValue as ContextValue2, EntityDef, InferRouterContext, MutationDef, Observable, OptimisticDSL, QueryDef, Resolvers, RouterDef } from "@sylphx/lens-core";
+import { AnyQueryDef, ContextValue as ContextValue2, EntityDef, InferRouterContext, MutationDef, Observable, OptimisticDSL, QueryDef, Resolvers, RouterDef } from "@sylphx/lens-core";
 /**
 * @sylphx/lens-server - Plugin System Types
 *
@@ -461,7 +461,7 @@ interface SelectionObject {
 /** Entity map type */
 type EntitiesMap = Record<string, EntityDef<string, any>>;
 /** Queries map type */
-type QueriesMap = Record<string, QueryDef<unknown, unknown>>;
+type QueriesMap = Record<string, AnyQueryDef<unknown, unknown>>;
 /** Mutations map type */
 type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
 /** Operation metadata for handshake */

package/dist/index.js

@@ -35,14 +35,18 @@ function extendContext(current, extension) {
 }
 // src/server/create.ts
 import {
+  collectModelsFromOperations,
+  collectModelsFromRouter,
   createEmit,
   createResolverFromEntity,
   flattenRouter,
   hashValue,
   hasInlineResolvers,
   isEntityDef,
+  isModelDef,
   isMutationDef,
   isQueryDef,
+  mergeModelCollections,
   valuesEqual
 } from "@sylphx/lens-core";
 
@@ -354,15 +358,23 @@ class LensServerImpl {
     }
     this.queries = queries;
     this.mutations = mutations;
-    const entities = { ...config.entities ?? {} };
+    const autoCollected = config.router ? collectModelsFromRouter(config.router) : collectModelsFromOperations(queries, mutations);
+    const entitiesFromConfig = config.entities ?? {};
+    const mergedModels = mergeModelCollections(autoCollected, entitiesFromConfig);
     if (config.resolvers) {
       for (const resolver of config.resolvers) {
         const entityName = resolver.entity._name;
-        if (entityName && !entities[entityName]) {
-          entities[entityName] = resolver.entity;
+        if (entityName && !mergedModels.has(entityName)) {
+          mergedModels.set(entityName, resolver.entity);
         }
       }
     }
+    const entities = {};
+    for (const [name, model] of mergedModels) {
+      if (isEntityDef(model) || isModelDef(model)) {
+        entities[name] = model;
+      }
+    }
     this.entities = entities;
     this.resolverMap = this.buildResolverMap(config.resolvers, entities);
     this.contextFactory = config.context ?? (() => ({}));
@@ -415,7 +427,7 @@ class LensServerImpl {
       }
     }
     for (const [name, entity] of Object.entries(entities)) {
-      if (!isEntityDef(entity))
+      if (!isEntityDef(entity) && !isModelDef(entity))
         continue;
       if (resolverMap.has(name))
         continue;

package/package.json

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

package/src/server/create.ts

@@ -17,6 +17,8 @@
 
 import {
 	type ContextValue,
+	collectModelsFromOperations,
+	collectModelsFromRouter,
 	createEmit,
 	createResolverFromEntity,
 	type Emit,
@@ -27,8 +29,10 @@ import {
 	hasInlineResolvers,
 	type InferRouterContext,
 	isEntityDef,
+	isModelDef,
 	isMutationDef,
 	isQueryDef,
+	mergeModelCollections,
 	type Observable,
 	type ResolverDef,
 	type RouterDef,
@@ -192,16 +196,34 @@ class LensServerImpl<
 		this.queries = queries as Q;
 		this.mutations = mutations as M;
 
-		// Build entities map: explicit config + auto-extracted from resolvers
-		const entities: EntitiesMap = { ...(config.entities ?? {}) };
+		// Build entities map (priority: explicit config > router > resolvers)
+		// Auto-track models from router return types (new behavior)
+		const autoCollected = config.router
+			? collectModelsFromRouter(config.router)
+			: collectModelsFromOperations(queries, mutations);
+
+		// Merge: explicit entities override auto-collected
+		const entitiesFromConfig = config.entities ?? {};
+		const mergedModels = mergeModelCollections(autoCollected, entitiesFromConfig);
+
+		// Also extract from explicit resolvers (legacy)
 		if (config.resolvers) {
 			for (const resolver of config.resolvers) {
 				const entityName = resolver.entity._name;
-				if (entityName && !entities[entityName]) {
-					entities[entityName] = resolver.entity;
+				if (entityName && !mergedModels.has(entityName)) {
+					mergedModels.set(entityName, resolver.entity);
 				}
 			}
 		}
+
+		// Convert Map to Record for entities (supports both EntityDef and ModelDef)
+		const entities: EntitiesMap = {};
+		for (const [name, model] of mergedModels) {
+			// Both ModelDef and EntityDef work as EntitiesMap values
+			if (isEntityDef(model) || isModelDef(model)) {
+				entities[name] = model as EntityDef<string, any>;
+			}
+		}
 		this.entities = entities;
 
 		// Build resolver map: explicit resolvers + auto-converted from entities with inline resolvers
@@ -278,12 +300,13 @@ class LensServerImpl<
 			}
 		}
 
-		// 2. Auto-convert entities with inline resolvers (if not already in map)
+		// 2. Auto-convert entities/models with inline resolvers (if not already in map)
 		for (const [name, entity] of Object.entries(entities)) {
-			if (!isEntityDef(entity)) continue;
+			// Support both EntityDef and ModelDef
+			if (!isEntityDef(entity) && !isModelDef(entity)) continue;
 			if (resolverMap.has(name)) continue; // Explicit resolver takes priority
 
-			// Check if entity has inline resolvers
+			// Check if entity/model has inline resolvers
 			if (hasInlineResolvers(entity)) {
 				const resolver = createResolverFromEntity(entity);
 				resolverMap.set(name, resolver);

package/src/server/types.ts

@@ -5,6 +5,7 @@
  */
 
 import type {
+	AnyQueryDef,
 	ContextValue,
 	EntityDef,
 	InferRouterContext,
@@ -51,7 +52,7 @@ export interface SelectionObject {
 export type EntitiesMap = Record<string, EntityDef<string, any>>;
 
 /** Queries map type */
-export type QueriesMap = Record<string, QueryDef<unknown, unknown>>;
+export type QueriesMap = Record<string, AnyQueryDef<unknown, unknown>>;
 
 /** Mutations map type */
 export type MutationsMap = Record<string, MutationDef<unknown, unknown>>;