@sylphx/lens-server 4.0.0 → 4.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @sylphx/lens-server
 
-Server runtime for the Lens API framework with WebSocket support.
+Server runtime for the Lens API framework.
 
 ## Installation
 
@@ -8,168 +8,120 @@ Server runtime for the Lens API framework with WebSocket support.
 bun add @sylphx/lens-server
 ```
 
-## Usage
-
-### Basic Server Setup
+## Quick Start
 
 ```typescript
-import { createApp, createHandler } from "@sylphx/lens-server";
-import { lens, id, string, list, nullable, router } from "@sylphx/lens-core";
+import { createApp } from "@sylphx/lens-server";
+import { model, id, string, list, router, lens } from "@sylphx/lens-core";
 import { z } from "zod";
 
-// Define context type
-interface AppContext {
-  db: Database;
-  user: User | null;
-}
-
-// Create typed builders
-const { model, query, mutation } = lens<AppContext>();
-
-// Define models with inline resolvers
+// Define models
 const User = model("User", {
   id: id(),
   name: string(),
   email: string(),
-  posts: list(() => Post),
-}).resolve({
-  posts: ({ source, ctx }) =>
-    ctx.db.posts.filter(p => p.authorId === source.id)
 });
 
-const Post = model("Post", {
-  id: id(),
-  title: string(),
-  authorId: string(),
-});
+// Create typed builders
+const { query, mutation, resolver } = lens<{ db: Database }>();
+
+// Define resolver
+const userResolver = resolver(User, (t) => ({
+  id: t.expose('id'),
+  name: t.expose('name'),
+  email: t.expose('email'),
+}));
 
 // Define operations
 const appRouter = router({
   user: {
     get: query()
-      .input(z.object({ id: z.string() }))
+      .args(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)),
+      .resolve(({ args, ctx }) => ctx.db.users.get(args.id)!),
 
     list: query()
-      .returns(list(User))  // User[]
+      .returns(list(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!
+// Create app
 const app = createApp({
-  router: appRouter,  // Models extracted from .returns()
-  context: () => ({
-    db: database,
-    user: getCurrentUser(),
-  }),
+  router: appRouter,
+  entities: { User },
+  resolvers: [userResolver],
+  context: () => ({ db: database }),
 });
 
-// Start server
-const handler = createHandler(app);
-Bun.serve({ port: 3000, fetch: handler });
+// Start server - app is directly callable
+Bun.serve({ fetch: app });
 ```
 
-### With Optimistic Updates
+## Runtime Support
 
-```typescript
-import { createApp, optimisticPlugin } from "@sylphx/lens-server";
-import { lens, id, string, router } from "@sylphx/lens-core";
-import { entity as e, temp, now } from "@sylphx/reify";
+Works with any runtime - app is directly callable:
 
-// Enable optimistic plugin
-const { model, query, mutation, plugins } = lens<AppContext>()
-  .withPlugins([optimisticPlugin()]);
+```typescript
+// Bun
+Bun.serve({ fetch: app })
 
-const Message = model("Message", {
-  id: id(),
-  content: string(),
-  createdAt: string(),
-});
+// Deno
+Deno.serve(app)
 
-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)),
-  },
-});
+// Cloudflare Workers
+export default app
 
-const app = createApp({
-  router: appRouter,
-  plugins,  // Include optimistic plugin
-  context: () => ({ ... }),
-});
+// Node.js (with adapter)
+import { createServer } from "node:http";
+import { toNodeHandler } from "@whatwg-node/server";
+createServer(toNodeHandler(app)).listen(3000);
 ```
 
-### Live Queries
+## HTTP Endpoints
 
-```typescript
-// query comes from lens<AppContext>() above
+The `app.fetch` handler provides:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | POST | Execute operations |
+| `/__lens/metadata` | GET | Server metadata |
+| `/__lens/health` | GET | Health check |
 
-// Live query with Publisher pattern
+## Live Queries
+
+For real-time updates, use the Publisher pattern:
+
+```typescript
 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
+  .args(z.object({ id: z.string() }))
+  .resolve(({ args, ctx }) => ctx.db.users.get(args.id)!)
+  .subscribe(({ args, ctx }) => ({ emit, onCleanup }) => {
+    const unsub = ctx.db.users.onChange(args.id, (user) => {
+      emit(user);
     });
-    onCleanup(unsub);  // Cleanup on disconnect
+    onCleanup(unsub);
   });
 ```
 
-### WebSocket Handler
+## Optimistic Updates
 
 ```typescript
-import { createApp, createHandler, createWSHandler } from "@sylphx/lens-server";
-
-const app = createApp({ ... });
+import { optimisticPlugin } from "@sylphx/lens-server";
 
-// HTTP handler
-const httpHandler = createHandler(app);
+const { mutation, plugins } = lens<AppContext>()
+  .withPlugins([optimisticPlugin()]);
 
-// WebSocket handler
-const wsHandler = createWSHandler(app);
+const updateUser = mutation()
+  .args(z.object({ id: z.string(), name: z.string() }))
+  .returns(User)
+  .optimistic("merge")
+  .resolve(({ args, ctx }) => ctx.db.users.update(args));
 
-Bun.serve({
-  port: 3000,
-  fetch(req, server) {
-    if (req.headers.get("upgrade") === "websocket") {
-      return wsHandler.upgrade(req, server);
-    }
-    return httpHandler(req);
-  },
-  websocket: wsHandler.websocket,
+const app = createApp({
+  router: appRouter,
+  plugins,
+  // ...
 });
 ```
 
@@ -177,57 +129,21 @@ Bun.serve({
 
 ```typescript
 createApp({
-  // Required (at least one)
+  // Required
   router: RouterDef,           // Namespaced operations
 
-  // Optional (models auto-tracked from router!)
-  entities: EntitiesMap,       // Explicit models (optional, for overrides)
-  plugins: ServerPlugin[],     // Server plugins (optimistic, clientState, etc.)
+  // Entities & Resolvers
+  entities: EntitiesMap,       // Models for normalization
+  resolvers: ResolverDef[],    // Field resolvers array
+
+  // Optional
+  plugins: ServerPlugin[],     // Server plugins (optimistic, 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